meadow-connection-sqlite 1.0.12 → 1.0.14

package/README.md

@@ -10,12 +10,13 @@ A SQLite database connection provider for the Meadow ORM. Wraps [better-sqlite3]
 
 ## Features
 
-- **Better-SQLite3 Wrapper** - Synchronous, high-performance SQLite access via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
-- **Fable Service Provider** - Registers with a Fable instance for dependency injection, logging, and configuration
-- **WAL Journal Mode** - Automatically enables Write-Ahead Logging for performance on connect
-- **Schema-Driven DDL** - Generates `CREATE TABLE` statements from Meadow table schemas with support for ID, GUID, ForeignKey, Numeric, Decimal, String, Text, DateTime, and Boolean column types
-- **Connection Safety** - Guards against double-connect and missing file path errors with descriptive logging
-- **Direct Database Access** - Exposes the underlying `better-sqlite3` database instance via `db` getter
+- **Better-SQLite3 Wrapper** -- Synchronous, high-performance SQLite access via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
+- **Fable Service Provider** -- Registers with a Fable instance for dependency injection, logging, and configuration
+- **WAL Journal Mode** -- Automatically enables Write-Ahead Logging for performance on connect
+- **Schema-Driven DDL** -- Generates `CREATE TABLE` statements from Meadow table schemas with support for ID, GUID, ForeignKey, Numeric, Decimal, String, Text, DateTime, and Boolean column types
+- **In-Memory Mode** -- Use `:memory:` as the file path for ephemeral databases in tests and prototypes
+- **Connection Safety** -- Guards against double-connect and missing file path errors with descriptive logging
+- **Direct Database Access** -- Exposes the underlying `better-sqlite3` database instance and module via getters
 
 ## Installation
 
@@ -167,8 +168,13 @@ npm run coverage
 
 ## Related Packages
 
-- [meadow](https://github.com/stevenvelozo/meadow) - Data access and ORM
-- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+- [meadow](https://github.com/stevenvelozo/meadow) -- Data access and ORM
+- [foxhound](https://github.com/stevenvelozo/foxhound) -- Query DSL used by Meadow
+- [stricture](https://github.com/stevenvelozo/stricture) -- Schema definition tool
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- RESTful endpoint generation
+- [meadow-connection-mysql](https://github.com/stevenvelozo/meadow-connection-mysql) -- MySQL connection provider
+- [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) -- MSSQL connection provider
+- [fable](https://github.com/stevenvelozo/fable) -- Application services framework
 
 ## License
 

package/docs/README.md

@@ -143,6 +143,14 @@ let _Fable = new libFable(
 
 The provider manages the connection lifecycle and exposes the raw `better-sqlite3` `Database` object. All queries go through better-sqlite3's synchronous API — there are no promises or callbacks for individual statements.
 
+## Learn More
+
+- [Quickstart Guide](quickstart.md) -- Five-step walkthrough from install to Meadow ORM integration
+- [Architecture & Design](architecture.md) -- Connection lifecycle, query model, and data flow diagrams
+- [Schema & Table Creation](schema.md) -- Column type mapping and DDL generation
+- [API Reference](api/reference.md) -- Complete reference for every property and method
+- [Full Pipeline Example](examples-pipeline.md) -- End-to-end CRUD pipeline with transactions and aggregates
+
 ## Companion Modules
 
 | Module | Purpose |
@@ -151,3 +159,4 @@ The provider manages the connection lifecycle and exposes the raw `better-sqlite
 | [FoxHound](/meadow/foxhound/) | Query DSL and SQL generation |
 | [meadow-connection-mysql](/meadow/meadow-connection-mysql/) | MySQL connection provider |
 | [meadow-connection-mssql](/meadow/meadow-connection-mssql/) | MSSQL connection provider |
+| [meadow-connection-rocksdb](/meadow/meadow-connection-rocksdb/) | RocksDB key-value provider |

package/docs/{cover.md → _cover.md}

@@ -1,5 +1,7 @@
 # Meadow Connection SQLite
 
+<small>v1.0.12</small>
+
 > SQLite database provider for the Meadow data layer
 
 Connect any Fable application to a local SQLite database through the service provider pattern. Built on better-sqlite3 for fast synchronous access with WAL journaling, automatic file creation, and in-memory database support.
@@ -8,8 +10,10 @@ Connect any Fable application to a local SQLite database through the service pro
 - **Synchronous API** -- All queries run synchronously through better-sqlite3's native bindings
 - **WAL Journaling** -- Write-Ahead Logging enabled automatically for concurrent read/write performance
 - **In-Memory Mode** -- Use `:memory:` as the file path for ephemeral databases in tests and prototypes
+- **Schema-Driven DDL** -- Generate CREATE TABLE statements from Meadow table schemas
 - **Service Integration** -- Registers as a Fable service with dependency injection and lifecycle logging
 
-[Quick Start](README.md)
-[API Reference](api.md)
+[Quick Start](quickstart.md)
+[API Reference](api/reference.md)
+[Architecture](architecture.md)
 [GitHub](https://github.com/stevenvelozo/meadow-connection-sqlite)

package/docs/_sidebar.md

@@ -1,10 +1,25 @@
 - Getting Started
 
   - [Overview](README.md)
+  - [Quickstart](quickstart.md)
 
-- Reference
+- Architecture
 
-  - [API Reference](api.md)
+  - [Design & Data Flow](architecture.md)
+  - [Schema & Table Creation](schema.md)
+
+- API Reference
+
+  - [Full Reference](api/reference.md)
+  - [connectAsync](api/connectAsync.md)
+  - [connect](api/connect.md)
+  - [db](api/db.md)
+  - [SQLite](api/SQLite.md)
+  - [preparedStatement](api/preparedStatement.md)
+  - [generateCreateTableStatement](api/generateCreateTableStatement.md)
+  - [createTable](api/createTable.md)
+  - [createTables](api/createTables.md)
+  - [generateDropTableStatement](api/generateDropTableStatement.md)
 
 - Examples
 
@@ -16,5 +31,7 @@
   - [FoxHound](/meadow/foxhound/)
   - [MySQL Connector](/meadow/meadow-connection-mysql/)
   - [MSSQL Connector](/meadow/meadow-connection-mssql/)
+  - [RocksDB Connector](/meadow/meadow-connection-rocksdb/)
   - [Fable](/fable/fable/)
+  - [Stricture](/meadow/stricture/)
   - [Indoctrinate](/utility/indoctrinate/)

package/docs/_topbar.md

@@ -1,5 +1,8 @@
 # Meadow Connection SQLite
 
 - [Overview](README.md)
-- [API Reference](api.md)
+- [Quickstart](quickstart.md)
+- [Architecture](architecture.md)
+- [API Reference](api/reference.md)
+- [Pipeline Example](examples-pipeline.md)
 - [GitHub](https://github.com/stevenvelozo/meadow-connection-sqlite)

package/docs/api/SQLite.md

@@ -0,0 +1,55 @@
+# SQLite (getter)
+
+Returns the `better-sqlite3` module constructor for direct access to the underlying library.
+
+## Signature
+
+```javascript
+get SQLite()
+```
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `function` | The `better-sqlite3` module (Database constructor) |
+
+## Primary Use
+
+The `SQLite` getter provides access to the raw `better-sqlite3` module. This is useful for:
+
+- Creating additional database instances outside the provider
+- Accessing `better-sqlite3` constants or utilities
+- Type checking against the constructor
+
+```javascript
+let tmpSQLiteConstructor = _Fable.MeadowSQLiteProvider.SQLite;
+```
+
+## Creating an Additional Database
+
+```javascript
+let tmpSQLite = _Fable.MeadowSQLiteProvider.SQLite;
+
+// Open a second database independently
+let tmpSecondDB = new tmpSQLite('./data/secondary.db');
+tmpSecondDB.pragma('journal_mode = WAL');
+
+let tmpRows = tmpSecondDB.prepare('SELECT * FROM Log').all();
+
+tmpSecondDB.close();
+```
+
+## Comparison with db Getter
+
+| Getter | Returns | Purpose |
+|--------|---------|---------|
+| `db` | Database instance | The connected database for queries |
+| `SQLite` | Module constructor | The better-sqlite3 library itself |
+
+The `db` getter returns the database handle opened by `connectAsync()`. The `SQLite` getter returns the library that creates those handles.
+
+## Related
+
+- [db](db.md) -- The connected database instance for queries
+- [connectAsync](connectAsync.md) -- Open the database connection

package/docs/api/connect.md

@@ -0,0 +1,66 @@
+# connect()
+
+Synchronous convenience wrapper that calls `connectAsync()` without a callback. Logs a warning about potential race conditions.
+
+## Signature
+
+```javascript
+connect()
+```
+
+## Parameters
+
+None.
+
+## Return Value
+
+None.
+
+## Behavior
+
+Calls `connectAsync()` internally without passing a callback. The provider logs a warning:
+
+```
+Meadow-Connection-SQLite connect() called without a callback; this could
+result in race conditions — use connectAsync(callback) instead.
+```
+
+## Why This Exists
+
+`connect()` is provided for legacy compatibility and quick prototyping. Because the underlying better-sqlite3 library opens databases synchronously, the connection actually completes immediately — but the method still logs a warning because the Fable service pattern expects asynchronous lifecycle management.
+
+## Usage
+
+```javascript
+_Fable.MeadowSQLiteProvider.connect();
+
+// The database is ready immediately (better-sqlite3 is synchronous)
+// but the warning is logged to encourage using connectAsync() instead
+if (_Fable.MeadowSQLiteProvider.connected)
+{
+	let tmpDB = _Fable.MeadowSQLiteProvider.db;
+	tmpDB.exec('CREATE TABLE IF NOT EXISTS Test (id INTEGER PRIMARY KEY)');
+}
+```
+
+## Recommended Alternative
+
+Always prefer `connectAsync()` for production code:
+
+```javascript
+_Fable.MeadowSQLiteProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		if (pError)
+		{
+			_Fable.log.error(`Connection failed: ${pError}`);
+			return;
+		}
+		// Safe to use the database here
+	});
+```
+
+## Related
+
+- [connectAsync](connectAsync.md) -- Recommended connection method
+- [db](db.md) -- Access the database after connecting

package/docs/api/connectAsync.md

@@ -0,0 +1,121 @@
+# connectAsync(fCallback)
+
+Opens a connection to the SQLite database file specified in configuration. This is the recommended way to connect.
+
+## Signature
+
+```javascript
+connectAsync(fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function` | Callback receiving `(error, database)` |
+
+## Return Value
+
+None. Results are delivered via the callback.
+
+## Callback Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pError` | `Error \| null` | Error object if connection failed, `null` on success |
+| `pDatabase` | `Database` | The better-sqlite3 Database instance |
+
+## Behavior
+
+1. If `SQLiteFilePath` is not configured, calls back with an error immediately
+2. If already connected, logs an error and calls back with the existing database (idempotent)
+3. Creates a new `better-sqlite3` Database instance at the configured file path
+4. The database file is created automatically if it does not exist
+5. Enables WAL (Write-Ahead Logging) journal mode for performance
+6. Sets `this.connected = true` on success
+
+## Basic Usage
+
+```javascript
+_Fable.MeadowSQLiteProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		if (pError)
+		{
+			_Fable.log.error(`Connection failed: ${pError}`);
+			return;
+		}
+
+		// pDatabase is the same as _Fable.MeadowSQLiteProvider.db
+		let tmpBooks = pDatabase.prepare('SELECT * FROM Book').all();
+		console.log(`Found ${tmpBooks.length} books`);
+	});
+```
+
+## Double-Connect Guard
+
+Calling `connectAsync()` on an already-connected provider logs an error but does not throw. It returns the existing database:
+
+```javascript
+_Fable.MeadowSQLiteProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		// First connection — succeeds normally
+
+		_Fable.MeadowSQLiteProvider.connectAsync(
+			(pError, pDatabase2) =>
+			{
+				// Logs: "...is already connected - skipping the second connect call."
+				// pDatabase2 is the same instance as pDatabase
+			});
+	});
+```
+
+## Missing File Path
+
+If `SQLiteFilePath` is not set in either the constructor options or Fable settings:
+
+```javascript
+_Fable.MeadowSQLiteProvider.connectAsync(
+	(pError) =>
+	{
+		// pError contains: "...database file path is invalid;
+		// SQLiteFilePath must be in either fable.settings.SQLite
+		// or passed as an option to the service provider."
+	});
+```
+
+## In-Memory Database
+
+Use `:memory:` for ephemeral databases that exist only in RAM:
+
+```javascript
+let _Fable = new libFable(
+	{
+		"SQLite": { "SQLiteFilePath": ":memory:" }
+	});
+
+// ... register and instantiate provider ...
+
+_Fable.MeadowSQLiteProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		// Database exists only in memory
+		// Discarded when the connection closes or process exits
+	});
+```
+
+## Missing Callback Warning
+
+If `connectAsync()` is called without a callback, the provider logs an error:
+
+```
+Meadow-Connection-SQLite connect() called without a callback; this could
+result in race conditions — use connectAsync(callback) instead.
+```
+
+## Related
+
+- [connect](connect.md) -- Synchronous wrapper (not recommended)
+- [db](db.md) -- Access the database after connecting
+- [pool](../api/reference.md) -- Full API reference

package/docs/api/createTable.md

@@ -0,0 +1,96 @@
+# createTable(pMeadowTableSchema, fCallback)
+
+Generates a `CREATE TABLE IF NOT EXISTS` statement from a Meadow table schema and executes it against the connected database.
+
+## Signature
+
+```javascript
+createTable(pMeadowTableSchema, fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMeadowTableSchema` | `object` | Meadow table schema with `TableName` and `Columns` array |
+| `fCallback` | `function` | Callback receiving `(error)` |
+
+## Return Value
+
+None. Results are delivered via the callback.
+
+## Behavior
+
+1. Calls `generateCreateTableStatement(pMeadowTableSchema)` to build the DDL
+2. Executes the DDL using `db.exec()`
+3. Calls back with `undefined` on success, or an error if the DDL fails
+
+Because the generated DDL uses `CREATE TABLE IF NOT EXISTS`, calling `createTable()` for an already-existing table is a no-op — it does not error.
+
+## Basic Usage
+
+```javascript
+let tmpBookSchema =
+{
+	TableName: 'Book',
+	Columns:
+	[
+		{ Column: 'IDBook', DataType: 'ID' },
+		{ Column: 'GUIDBook', DataType: 'GUID' },
+		{ Column: 'Title', DataType: 'String', Size: '256' },
+		{ Column: 'Author', DataType: 'String', Size: '128' },
+		{ Column: 'Price', DataType: 'Decimal', Size: '10,2' }
+	]
+};
+
+_Fable.MeadowSQLiteProvider.createTable(tmpBookSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			_Fable.log.error(`Create table failed: ${pError}`);
+			return;
+		}
+		_Fable.log.info('Book table created');
+	});
+```
+
+## Idempotent
+
+Safe to call multiple times. The second call is a no-op:
+
+```javascript
+_Fable.MeadowSQLiteProvider.createTable(tmpBookSchema,
+	(pError) =>
+	{
+		// Table created
+
+		_Fable.MeadowSQLiteProvider.createTable(tmpBookSchema,
+			(pError) =>
+			{
+				// No error — "IF NOT EXISTS" handles it
+			});
+	});
+```
+
+## Error Handling
+
+Errors from `db.exec()` (e.g. invalid column definitions) are passed to the callback:
+
+```javascript
+_Fable.MeadowSQLiteProvider.createTable(tmpBadSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('DDL execution failed:', pError.message);
+		}
+	});
+```
+
+## Related
+
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate DDL without executing
+- [createTables](createTables.md) -- Create multiple tables at once
+- [generateDropTableStatement](generateDropTableStatement.md) -- Drop a table
+- [Schema & Table Creation](../schema.md) -- Full type mapping reference

package/docs/api/createTables.md

@@ -0,0 +1,91 @@
+# createTables(pMeadowSchema, fCallback)
+
+Creates all tables defined in a Meadow schema object. Tables are created sequentially.
+
+## Signature
+
+```javascript
+createTables(pMeadowSchema, fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMeadowSchema` | `object` | Meadow schema with a `Tables` array of table schemas |
+| `fCallback` | `function` | Callback receiving `(error)` |
+
+## Return Value
+
+None. Results are delivered via the callback.
+
+## Schema Object Format
+
+```javascript
+let tmpSchema =
+{
+	Tables:
+	[
+		{
+			TableName: 'Book',
+			Columns:
+			[
+				{ Column: 'IDBook', DataType: 'ID' },
+				{ Column: 'GUIDBook', DataType: 'GUID' },
+				{ Column: 'Title', DataType: 'String', Size: '256' }
+			]
+		},
+		{
+			TableName: 'Author',
+			Columns:
+			[
+				{ Column: 'IDAuthor', DataType: 'ID' },
+				{ Column: 'GUIDAuthor', DataType: 'GUID' },
+				{ Column: 'Name', DataType: 'String', Size: '128' }
+			]
+		},
+		{
+			TableName: 'BookAuthor',
+			Columns:
+			[
+				{ Column: 'IDBookAuthor', DataType: 'ID' },
+				{ Column: 'IDBook', DataType: 'ForeignKey' },
+				{ Column: 'IDAuthor', DataType: 'ForeignKey' }
+			]
+		}
+	]
+};
+```
+
+## Basic Usage
+
+```javascript
+_Fable.MeadowSQLiteProvider.createTables(tmpSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			_Fable.log.error(`Schema creation failed: ${pError}`);
+			return;
+		}
+
+		_Fable.log.info('All tables created');
+	});
+```
+
+## Behavior
+
+- Iterates through `pMeadowSchema.Tables` using `fable.Utility.eachLimit` with concurrency 1
+- Each table is created by calling `createTable()` internally
+- If any table creation fails, the error is passed to the callback
+- Uses `CREATE TABLE IF NOT EXISTS`, so existing tables are skipped without error
+
+## Sequential Execution
+
+Tables are created one at a time (concurrency = 1). This ensures that tables referenced by foreign keys can be created in the order you specify in the `Tables` array.
+
+## Related
+
+- [createTable](createTable.md) -- Create a single table
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate DDL without executing
+- [Schema & Table Creation](../schema.md) -- Full type mapping reference