meadow-connection-sqlite 1.0.12 → 1.0.14

package/docs/api/db.md

@@ -0,0 +1,145 @@
+# db (getter)
+
+Returns the underlying `better-sqlite3` Database instance for direct query access.
+
+## Signature
+
+```javascript
+get db()
+```
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `Database` | The better-sqlite3 Database instance (after `connectAsync()`) |
+| `false` | Before connection |
+
+## Primary Use
+
+The `db` getter is the main entry point for all query operations. All queries go through better-sqlite3's synchronous API:
+
+```javascript
+let tmpDB = _Fable.MeadowSQLiteProvider.db;
+
+// DDL — run raw SQL (no return value)
+tmpDB.exec(`
+	CREATE TABLE IF NOT EXISTS Book (
+		IDBook INTEGER PRIMARY KEY AUTOINCREMENT,
+		Title TEXT DEFAULT '',
+		Author TEXT DEFAULT ''
+	)
+`);
+
+// INSERT / UPDATE / DELETE — returns { changes, lastInsertRowid }
+let tmpResult = tmpDB.prepare('INSERT INTO Book (Title, Author) VALUES (?, ?)').run('Dune', 'Frank Herbert');
+console.log(tmpResult.lastInsertRowid); // => 1
+console.log(tmpResult.changes);         // => 1
+
+// SELECT single row — returns object or undefined
+let tmpBook = tmpDB.prepare('SELECT * FROM Book WHERE IDBook = ?').get(1);
+console.log(tmpBook.Title); // => 'Dune'
+
+// SELECT all rows — returns array of objects
+let tmpBooks = tmpDB.prepare('SELECT * FROM Book').all();
+console.log(tmpBooks.length); // => 1
+```
+
+## Prepared Statement Methods
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `stmt.run(params...)` | `{ changes, lastInsertRowid }` | INSERT, UPDATE, DELETE |
+| `stmt.get(params...)` | object or `undefined` | SELECT single row |
+| `stmt.all(params...)` | array of objects | SELECT all matching rows |
+
+## Named Parameters
+
+better-sqlite3 supports named parameters prefixed with `@`, `$`, or `:`:
+
+```javascript
+let tmpStmt = tmpDB.prepare(
+	'SELECT * FROM Book WHERE Author = @author AND YearPublished > @year'
+);
+
+let tmpBooks = tmpStmt.all({ author: 'Isaac Asimov', year: 1950 });
+```
+
+## Transactions
+
+Wrap a function in a transaction for atomic operations:
+
+```javascript
+let tmpBulkInsert = tmpDB.transaction(
+	(pBooks) =>
+	{
+		let tmpStmt = tmpDB.prepare('INSERT INTO Book (Title, Author) VALUES (?, ?)');
+		for (let tmpBook of pBooks)
+		{
+			tmpStmt.run(tmpBook.Title, tmpBook.Author);
+		}
+	});
+
+tmpBulkInsert([
+	{ Title: 'Foundation', Author: 'Isaac Asimov' },
+	{ Title: 'Dune', Author: 'Frank Herbert' }
+]);
+```
+
+If any statement inside the transaction throws, the entire transaction is rolled back automatically.
+
+## Multi-Statement DDL
+
+`exec()` runs one or more SQL statements without returning data:
+
+```javascript
+tmpDB.exec(`
+	CREATE TABLE IF NOT EXISTS Book (
+		IDBook INTEGER PRIMARY KEY AUTOINCREMENT,
+		Title TEXT DEFAULT ''
+	);
+	CREATE INDEX IF NOT EXISTS idx_book_title ON Book(Title);
+`);
+```
+
+## PRAGMA Commands
+
+```javascript
+tmpDB.pragma('journal_mode');        // => [{ journal_mode: 'wal' }]
+tmpDB.pragma('table_info(Book)');    // => column info array
+```
+
+## Before Connection
+
+Returns `false` before `connectAsync()` is called:
+
+```javascript
+let tmpDB = _Fable.MeadowSQLiteProvider.db;
+// tmpDB => false (not connected yet)
+```
+
+Always check `connected` before accessing `db`:
+
+```javascript
+if (!_Fable.MeadowSQLiteProvider.connected)
+{
+	console.error('Not connected to SQLite.');
+	return;
+}
+
+let tmpDB = _Fable.MeadowSQLiteProvider.db;
+```
+
+## Closing the Database
+
+```javascript
+tmpDB.close();
+```
+
+After closing, further queries on this database instance will throw. The provider's `connected` property remains `true`.
+
+## Related
+
+- [connectAsync](connectAsync.md) -- Open the database connection
+- [SQLite](SQLite.md) -- Access the better-sqlite3 module constructor
+- [preparedStatement](preparedStatement.md) -- Alternative getter for the database handle

package/docs/api/generateCreateTableStatement.md

@@ -0,0 +1,109 @@
+# generateCreateTableStatement(pMeadowTableSchema)
+
+Generates a `CREATE TABLE IF NOT EXISTS` SQL statement from a Meadow table schema object. Returns the SQL string without executing it.
+
+## Signature
+
+```javascript
+generateCreateTableStatement(pMeadowTableSchema)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMeadowTableSchema` | `object` | Meadow table schema with `TableName` and `Columns` array |
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `string` | A `CREATE TABLE IF NOT EXISTS` SQL statement |
+
+## Schema Object Format
+
+```javascript
+let tmpSchema =
+{
+	TableName: 'Book',
+	Columns:
+	[
+		{ Column: 'IDBook', DataType: 'ID' },
+		{ Column: 'GUIDBook', DataType: 'GUID' },
+		{ Column: 'Title', DataType: 'String', Size: '256' },
+		{ Column: 'Author', DataType: 'String', Size: '128' },
+		{ Column: 'YearPublished', DataType: 'Numeric' },
+		{ Column: 'Price', DataType: 'Decimal', Size: '10,2' },
+		{ Column: 'InPrint', DataType: 'Boolean' },
+		{ Column: 'CreateDate', DataType: 'DateTime' },
+		{ Column: 'UpdateDate', DataType: 'DateTime' }
+	]
+};
+```
+
+Each column entry requires:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `Column` | string | Yes | Column name |
+| `DataType` | string | Yes | Meadow data type |
+| `Size` | string | No | Size specification (ignored by SQLite) |
+
+## Basic Usage
+
+```javascript
+let tmpDDL = _Fable.MeadowSQLiteProvider.generateCreateTableStatement(tmpSchema);
+console.log(tmpDDL);
+```
+
+Output:
+
+```sql
+CREATE TABLE IF NOT EXISTS Book (IDBook INTEGER PRIMARY KEY AUTOINCREMENT, GUIDBook TEXT DEFAULT '00000000-0000-0000-0000-000000000000', Title TEXT NOT NULL DEFAULT '', Author TEXT NOT NULL DEFAULT '', YearPublished INTEGER NOT NULL DEFAULT 0, Price REAL, InPrint INTEGER NOT NULL DEFAULT 0, CreateDate TEXT, UpdateDate TEXT);
+```
+
+## Type Mapping
+
+| Meadow DataType | SQLite Column Definition |
+|-----------------|--------------------------|
+| `ID` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `GUID` | `TEXT DEFAULT '00000000-0000-0000-0000-000000000000'` |
+| `ForeignKey` | `INTEGER NOT NULL DEFAULT 0` |
+| `Numeric` | `INTEGER NOT NULL DEFAULT 0` |
+| `Decimal` | `REAL` |
+| `String` | `TEXT NOT NULL DEFAULT ''` |
+| `Text` | `TEXT` |
+| `DateTime` | `TEXT` |
+| `Boolean` | `INTEGER NOT NULL DEFAULT 0` |
+
+### Notes
+
+- **Size is ignored** -- SQLite does not enforce `VARCHAR` length. The `Size` property is accepted for schema documentation but has no effect on the generated DDL.
+- **`CREATE TABLE IF NOT EXISTS`** -- Always idempotent; safe to run repeatedly.
+- **No column quoting** -- Column names are used as-is. SQLite does not require brackets or backticks.
+
+## Comparison with MySQL
+
+| Feature | MySQL | SQLite |
+|---------|-------|--------|
+| `ID` | `INT UNSIGNED NOT NULL AUTO_INCREMENT` + `PRIMARY KEY (col)` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `String(256)` | `VARCHAR(256)` | `TEXT` (size ignored) |
+| `Decimal(10,2)` | `DECIMAL(10,2)` | `REAL` |
+| `Boolean` | `TINYINT NOT NULL DEFAULT 0` | `INTEGER NOT NULL DEFAULT 0` |
+| Table quoting | `` `TableName` `` | `TableName` (unquoted) |
+
+## Comparison with MSSQL
+
+| Feature | MSSQL | SQLite |
+|---------|-------|--------|
+| `ID` | `INT IDENTITY(1,1)` + `PRIMARY KEY CLUSTERED ([col])` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `String(256)` | `[col] NVARCHAR(256)` | `TEXT` |
+| Schema prefix | `[dbo].[TableName]` | None |
+| Column quoting | `[ColumnName]` | Unquoted |
+
+## Related
+
+- [createTable](createTable.md) -- Generate and execute the DDL
+- [createTables](createTables.md) -- Create multiple tables at once
+- [generateDropTableStatement](generateDropTableStatement.md) -- Generate a DROP TABLE statement
+- [Schema & Table Creation](../schema.md) -- Full type mapping documentation

package/docs/api/generateDropTableStatement.md

@@ -0,0 +1,74 @@
+# generateDropTableStatement(pTableName)
+
+Generates a `DROP TABLE IF EXISTS` SQL statement for the given table name.
+
+## Signature
+
+```javascript
+generateDropTableStatement(pTableName)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pTableName` | `string` | The name of the table to drop |
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `string` | A `DROP TABLE IF EXISTS` SQL statement |
+
+## Basic Usage
+
+```javascript
+let tmpDropSQL = _Fable.MeadowSQLiteProvider.generateDropTableStatement('Book');
+console.log(tmpDropSQL);
+```
+
+Output:
+
+```sql
+DROP TABLE IF EXISTS Book;
+```
+
+## Executing the Drop
+
+The method only generates the SQL — it does not execute it. Use `db.exec()` to run it:
+
+```javascript
+let tmpDropSQL = _Fable.MeadowSQLiteProvider.generateDropTableStatement('Book');
+_Fable.MeadowSQLiteProvider.db.exec(tmpDropSQL);
+```
+
+## Idempotent
+
+The generated statement uses `IF EXISTS`, so dropping a table that does not exist is a no-op:
+
+```javascript
+let tmpDropSQL = _Fable.MeadowSQLiteProvider.generateDropTableStatement('NonExistentTable');
+_Fable.MeadowSQLiteProvider.db.exec(tmpDropSQL);
+// No error — IF EXISTS handles it
+```
+
+## Comparison with MSSQL
+
+| Feature | MSSQL | SQLite |
+|---------|-------|--------|
+| Syntax | `IF OBJECT_ID('dbo.Book', 'U') IS NOT NULL DROP TABLE [dbo].[Book]; GO` | `DROP TABLE IF EXISTS Book;` |
+| Schema prefix | `[dbo].[TableName]` | None |
+| Batch separator | `GO` | None needed |
+
+## Comparison with MySQL
+
+| Feature | MySQL | SQLite |
+|---------|-------|--------|
+| Syntax | `` DROP TABLE IF EXISTS `Book`; `` | `DROP TABLE IF EXISTS Book;` |
+| Quoting | Backticks | None |
+
+## Related
+
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate CREATE TABLE DDL
+- [createTable](createTable.md) -- Generate and execute CREATE TABLE
+- [db](db.md) -- Execute the drop statement via `db.exec()`

package/docs/api/preparedStatement.md

@@ -0,0 +1,67 @@
+# preparedStatement (getter)
+
+Returns the `better-sqlite3` Database instance if connected. Throws an error if the provider is not connected.
+
+## Signature
+
+```javascript
+get preparedStatement()
+```
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `Database` | The better-sqlite3 Database instance (when connected) |
+
+## Error Conditions
+
+Throws an error if the database is not connected:
+
+```
+The Meadow SQLite provider could not create a prepared statement;
+disconnected or no valid connection pool.
+```
+
+## Why This Exists
+
+The `preparedStatement` getter exists for API symmetry with the MSSQL connection provider, which returns a new `mssql.PreparedStatement` bound to the connection pool. In the SQLite provider, prepared statements are created directly on the Database instance via `db.prepare()`, so this getter simply returns the `db` handle itself.
+
+This allows code that references `provider.preparedStatement` to work across different Meadow connection providers.
+
+## Usage
+
+```javascript
+let tmpDB = _Fable.MeadowSQLiteProvider.preparedStatement;
+
+// Create and use a prepared statement
+let tmpStmt = tmpDB.prepare('SELECT * FROM Book WHERE IDBook = ?');
+let tmpBook = tmpStmt.get(42);
+```
+
+## Comparison with db Getter
+
+| Getter | Before Connection | After Connection |
+|--------|-------------------|------------------|
+| `db` | Returns `false` | Returns Database instance |
+| `preparedStatement` | Throws Error | Returns Database instance |
+
+Use `db` when you want to check for connection state gracefully. Use `preparedStatement` when you want a hard failure if the database is not connected.
+
+## Comparison with MSSQL Provider
+
+```javascript
+// MSSQL — each access creates a new PreparedStatement
+let tmpPS = _Fable.MeadowMSSQLProvider.preparedStatement;
+tmpPS.input('id', _Fable.MeadowMSSQLProvider.MSSQL.Int);
+tmpPS.prepare('SELECT * FROM Book WHERE IDBook = @id', ...);
+
+// SQLite — returns the Database handle (prepare directly)
+let tmpDB = _Fable.MeadowSQLiteProvider.preparedStatement;
+let tmpStmt = tmpDB.prepare('SELECT * FROM Book WHERE IDBook = ?');
+```
+
+## Related
+
+- [db](db.md) -- Primary database getter (returns `false` before connection)
+- [connectAsync](connectAsync.md) -- Open the database connection first

package/docs/api/reference.md

@@ -0,0 +1,192 @@
+# API Reference
+
+Complete reference for `MeadowConnectionSQLite`, the SQLite database connection provider for the Meadow data layer.
+
+---
+
+## Class: MeadowConnectionSQLite
+
+Extends `fable-serviceproviderbase`. Manages a connection to a SQLite database file through the [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) library.
+
+### Constructor
+
+```javascript
+new MeadowConnectionSQLite(pFable, pManifest, pServiceHash)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | object | A Fable instance |
+| `pManifest` | object | Service manifest / options (optional) |
+| `pServiceHash` | string | Service identifier |
+
+On construction:
+
+- Sets `serviceType` to `'MeadowConnectionSQLite'`
+- Sets `connected` to `false`
+- Reads `SQLiteFilePath` from `fable.settings.SQLite` if available
+
+The provider is not connected after construction — call `connectAsync()` to open the database.
+
+---
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| [`connected`](#connected) | `boolean` | Whether the database connection is open |
+| [`db`](db.md) | `Database \| false` | The raw better-sqlite3 Database instance |
+| [`SQLite`](SQLite.md) | `function` | The better-sqlite3 module constructor |
+| [`preparedStatement`](preparedStatement.md) | `Database \| Error` | Returns the Database instance if connected |
+| [`serviceType`](#servicetype) | `string` | Always `'MeadowConnectionSQLite'` |
+
+### connected
+
+Whether the database connection is open.
+
+**Type:** `boolean`
+
+```javascript
+if (_Fable.MeadowSQLiteProvider.connected)
+{
+	// Safe to use db
+}
+```
+
+### serviceType
+
+Always `'MeadowConnectionSQLite'`.
+
+**Type:** `string`
+
+---
+
+## Connection Methods
+
+| Method | Description |
+|--------|-------------|
+| [`connectAsync(fCallback)`](connectAsync.md) | Open the database and enable WAL (recommended) |
+| [`connect()`](connect.md) | Synchronous wrapper — logs a race-condition warning |
+
+---
+
+## DDL Methods
+
+| Method | Description |
+|--------|-------------|
+| [`generateCreateTableStatement(pSchema)`](generateCreateTableStatement.md) | Generate a `CREATE TABLE IF NOT EXISTS` statement |
+| [`createTable(pSchema, fCallback)`](createTable.md) | Generate and execute a CREATE TABLE statement |
+| [`createTables(pSchema, fCallback)`](createTables.md) | Create multiple tables from a Meadow schema |
+| [`generateDropTableStatement(pTableName)`](generateDropTableStatement.md) | Generate a `DROP TABLE IF EXISTS` statement |
+
+---
+
+## Configuration
+
+### Fable Settings
+
+```json
+{
+	"SQLite":
+	{
+		"SQLiteFilePath": "./data/myapp.db"
+	}
+}
+```
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `SQLiteFilePath` | string | Yes | File path or `:memory:` for in-memory databases |
+
+### Constructor Options
+
+Additional properties passed through to the `better-sqlite3` constructor:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `readonly` | boolean | `false` | Open the database in read-only mode |
+| `fileMustExist` | boolean | `false` | Error if the file does not exist |
+| `timeout` | number | `5000` | Milliseconds to wait when the database is locked |
+
+Constructor options override Fable settings, allowing multiple provider instances with different database files.
+
+---
+
+## Connection Behavior
+
+### WAL Journal Mode
+
+On successful connection, the provider automatically runs:
+
+```sql
+PRAGMA journal_mode = WAL;
+```
+
+Write-Ahead Logging provides significantly better concurrent read/write performance compared to SQLite's default rollback journal.
+
+### File Creation
+
+If the database file does not exist, better-sqlite3 creates it automatically. The directory must exist.
+
+### In-Memory Databases
+
+Set `SQLiteFilePath` to `":memory:"` for ephemeral databases:
+
+```javascript
+let _Fable = new libFable(
+	{
+		"SQLite": { "SQLiteFilePath": ":memory:" }
+	});
+```
+
+In-memory databases are discarded when the connection closes or the process exits.
+
+---
+
+## Column Type Mapping
+
+| Meadow DataType | SQLite Column Definition |
+|-----------------|--------------------------|
+| `ID` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `GUID` | `TEXT DEFAULT '00000000-0000-0000-0000-000000000000'` |
+| `ForeignKey` | `INTEGER NOT NULL DEFAULT 0` |
+| `Numeric` | `INTEGER NOT NULL DEFAULT 0` |
+| `Decimal` | `REAL` |
+| `String` | `TEXT NOT NULL DEFAULT ''` |
+| `Text` | `TEXT` |
+| `DateTime` | `TEXT` |
+| `Boolean` | `INTEGER NOT NULL DEFAULT 0` |
+
+See [Schema & Table Creation](../schema.md) for full details.
+
+---
+
+## Logging
+
+The provider logs connection events through the Fable logging system:
+
+| Event | Level | Message |
+|-------|-------|---------|
+| Connecting | `info` | `Meadow-Connection-SQLite connecting to file [path].` |
+| Connected | `info` | `Meadow-Connection-SQLite successfully connected to SQLite file [path].` |
+| Already connected | `error` | `...is already connected - skipping the second connect call.` |
+| Missing path | `error` | `...database file path is invalid; SQLiteFilePath must be in either...` |
+| Connection error | `error` | `...error connecting to SQLite file [path]: [error]` |
+| No callback | `error` | `...connect() called without a callback...` |
+
+---
+
+## Known Limitations
+
+- **No async queries** -- better-sqlite3 is synchronous by design. For CPU-bound workloads, consider running queries in a worker thread.
+- **No connection pooling** -- Unlike MySQL/MSSQL, SQLite uses a single database handle. Concurrent access is managed by WAL journaling.
+- **No size enforcement** -- SQLite ignores declared column sizes (e.g. `VARCHAR(256)` is treated as `TEXT`).
+
+---
+
+## Related
+
+- [Quickstart Guide](../quickstart.md) -- Get running in five steps
+- [Architecture & Design](../architecture.md) -- Lifecycle and data flow diagrams
+- [Schema & Table Creation](../schema.md) -- Column type mapping and DDL generation
+- [Full Pipeline Example](../examples-pipeline.md) -- End-to-end CRUD walkthrough