Meadow

▶ Read the Meadow Documentation — interactive docs with the full API reference.

A data access library providing magic where you want it, programmability where you don't.

Meadow is a JavaScript data broker that handles repetitive CRUD operations through a consistent, provider-agnostic interface. It abstracts database communication behind a unified API -- whether your data lives in MySQL, MSSQL, PostgreSQL, SQLite, MongoDB, RocksDB, or an in-browser ALASQL store, Meadow provides schema management, query generation, data marshalling, and automatic audit stamping while you focus on business logic.

Features

• Provider-Agnostic Design -- pluggable database backends through a consistent CRUD interface
• Schema-Driven -- define your data model once and get validation, default objects, and audit tracking for free
• FoxHound Query DSL -- fluent query builder that generates dialect-specific SQL, MongoDB queries, or key-value lookups
• Automatic Audit Tracking -- auto-populated create, update, and delete timestamps with user identity stamps
• Soft Deletes -- built-in logical deletion with automatic query filtering and undelete support
• GUID Uniqueness -- automatic GUID generation and uniqueness enforcement on record creation
• Raw Query Overrides -- escape hatch for custom SQL when the DSL is not enough
• Role-Based Authorization -- declarative access control per operation integrated with Meadow-Endpoints
• Fable Integration -- first-class service in the Fable ecosystem with logging, configuration, and dependency injection
• Browser Support -- ALASQL provider enables the same data access patterns in the browser via IndexedDB

Install

npm install meadow

Quick Example

const libFable = require('fable').new();
const libMeadow = require('meadow');

// Create a Meadow DAL for the "Book" entity
const meadow = libMeadow.new(libFable, 'Book')
	.setProvider('MySQL')
	.setDefaultIdentifier('IDBook')
	.setSchema([
		{ Column: 'IDBook', Type: 'AutoIdentity' },
		{ Column: 'GUIDBook', Type: 'AutoGUID' },
		{ Column: 'Title', Type: 'String', Size: '255' },
		{ Column: 'Author', Type: 'String', Size: '128' },
		{ Column: 'Metadata', Type: 'JSON' },
		{ Column: 'CreateDate', Type: 'CreateDate' },
		{ Column: 'CreatingIDUser', Type: 'CreateIDUser' },
		{ Column: 'UpdateDate', Type: 'UpdateDate' },
		{ Column: 'UpdatingIDUser', Type: 'UpdateIDUser' },
		{ Column: 'DeleteDate', Type: 'DeleteDate' },
		{ Column: 'DeletingIDUser', Type: 'DeleteIDUser' },
		{ Column: 'Deleted', Type: 'Deleted' }
	]);

// Create a record
const tmpCreateQuery = meadow.query.addRecord({ Title: 'Dune', Author: 'Frank Herbert' });
meadow.doCreate(tmpCreateQuery,
	(pError, pCreateQuery, pReadQuery, pRecord) =>
	{
		console.log('Created book:', pRecord.IDBook, '-', pRecord.Title);
	});

// Read a single record
meadow.doRead(meadow.query.addFilter('IDBook', 1),
	(pError, pQuery, pRecord) =>
	{
		console.log('Found:', pRecord.Title, 'by', pRecord.Author);
	});

// Read multiple records with pagination
meadow.doReads(meadow.query.setCap(25).setBegin(0),
	(pError, pQuery, pRecords) =>
	{
		console.log('Found', pRecords.length, 'books');
	});

Schema Column Types

Type	Description
AutoIdentity	Auto-increment primary key
AutoGUID	Automatically generated GUID
String	Variable-length string with optional Size
Text	Long text field
Numeric	Integer field
Decimal	Decimal field with Size as "precision,scale"
Boolean	Boolean flag
DateTime	Date/time field
CreateDate	Auto-populated timestamp on create
CreateIDUser	Auto-populated user ID on create
UpdateDate	Auto-populated timestamp on update
UpdateIDUser	Auto-populated user ID on update
DeleteDate	Auto-populated timestamp on delete
DeleteIDUser	Auto-populated user ID on delete
Deleted	Soft delete flag (enables logical deletion)
JSON	Structured JSON data (stored as TEXT, marshaled to/from objects)
JSONProxy	JSON stored in a different SQL column (uses StorageColumn for SQL, virtual name for objects)

CRUD Operations

Method	Callback Signature	Description
doCreate(pQuery, fCB)	(pError, pCreateQuery, pReadQuery, pRecord)	Insert a new record
doRead(pQuery, fCB)	(pError, pQuery, pRecord)	Read a single record
doReads(pQuery, fCB)	(pError, pQuery, pRecords)	Read multiple records
doUpdate(pQuery, fCB)	(pError, pUpdateQuery, pReadQuery, pRecord)	Update an existing record
doDelete(pQuery, fCB)	(pError, pQuery, pCount)	Delete a record (soft or hard)
doUndelete(pQuery, fCB)	(pError, pQuery, pCount)	Restore a soft-deleted record
doCount(pQuery, fCB)	(pError, pQuery, pCount)	Count matching records

Configuration Methods

Method	Returns	Description
setProvider(pName)	this	Set database provider (MySQL, MSSQL, PostgreSQL, SQLite, MongoDB, RocksDB, ALASQL, MeadowEndpoints, None)
setScope(pScope)	this	Set entity scope (table name)
setSchema(pSchema)	this	Set column schema array
setDefaultIdentifier(pId)	this	Set primary key column name
setIDUser(pIDUser)	this	Set user ID for audit stamps
setJsonSchema(pSchema)	this	Set JSON Schema v4 for validation
setDefault(pDefault)	this	Set default object template
setAuthorizer(pAuth)	this	Set role-based authorization rules
setDomain(pDomain)	this	Set entity domain grouping
loadFromPackage(pPath)	Meadow	Load schema from JSON file
loadFromPackageObject(pObj)	Meadow	Load schema from object

Properties

Property	Type	Description
scope	string	Entity scope name
schema	array	Column schema definitions
schemaFull	object	Full MeadowSchema with methods
jsonSchema	object	JSON Schema v4 definition
defaultIdentifier	string	Primary key column name
defaultGUIdentifier	string	GUID column name
userIdentifier	number	Current user ID
query	object	Cloned FoxHound query (fresh each access)
rawQueries	object	Raw query manager
provider	object	Active provider instance
providerName	string	Active provider name

Providers

Provider	Description	Connection Module
MySQL	MySQL/MariaDB via mysql2	meadow-connection-mysql
MSSQL	Microsoft SQL Server	meadow-connection-mssql
PostgreSQL	PostgreSQL	meadow-connection-postgresql
SQLite	Embedded SQLite via better-sqlite3	meadow-connection-sqlite
MongoDB	MongoDB document store	meadow-connection-mongodb
RocksDB	Embedded key-value store	meadow-connection-rocksdb
ALASQL	In-browser IndexedDB via ALASQL	Built-in
MeadowEndpoints	REST proxy to remote Meadow API	Built-in
None	No-op stub for testing	None required

Testing

npm test

Documentation

Detailed documentation is available in the docs/ folder:

npx docsify-cli serve docs

Related Packages

• foxhound -- query DSL for SQL and NoSQL generation
• stricture -- schema definition language
• meadow-endpoints -- automatic REST endpoint generation
• meadow-connection-mysql -- MySQL connection provider
• meadow-connection-mssql -- MSSQL connection provider
• meadow-connection-sqlite -- SQLite connection provider
• meadow-connection-postgresql -- PostgreSQL connection provider
• meadow-connection-mongodb -- MongoDB connection provider
• meadow-connection-rocksdb -- RocksDB connection provider
• fable -- application services framework
• orator -- API server abstraction

License

MIT

Contributing

Pull requests are welcome. For details on code of conduct, contribution process, and testing requirements, see the Retold Contributing Guide.