retold-data-service 2.0.12 → 2.0.14

package/docs/dal-access.md

@@ -1,87 +1,166 @@
 # DAL Access
 
-In addition to the REST endpoints, you can query your data directly through the Meadow DAL objects.
+After initialization, Retold Data Service exposes a Meadow DAL instance for every entity in your schema. Use these DAL objects for server-side data operations without going through the REST API.
 
-## Accessing DAL Objects
+## Accessing the DAL
 
-After initialization, every entity in your model has a DAL object accessible via `fable.DAL`:
+DAL objects are available on the Fable instance:
 
 ```javascript
-// Read a single record
-let tmpQuery = _Fable.DAL.Book.query.addFilter('IDBook', 42);
+// Access any entity's DAL
+let tmpBookDAL = _Fable.DAL.Book;
+let tmpAuthorDAL = _Fable.DAL.Author;
+```
+
+## Read Operations
+
+### Read Single Record
+
+```javascript
+let tmpQuery = _Fable.DAL.Book.query
+	.addFilter('IDBook', 42);
 
 _Fable.DAL.Book.doRead(tmpQuery,
-    (pError, pQuery, pRecord) =>
-    {
-        console.log('Found:', pRecord.Title);
-    });
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Book:', pRecord.Title);
+	});
 ```
 
-## Available Operations
+### Read Multiple Records
 
-| Method | Description |
-|--------|-------------|
-| `doCreate(query, callback)` | Insert a new record |
-| `doRead(query, callback)` | Read a single record |
-| `doReads(query, callback)` | Read multiple records |
-| `doUpdate(query, callback)` | Update an existing record |
-| `doDelete(query, callback)` | Soft-delete a record |
-| `doUndelete(query, callback)` | Restore a soft-deleted record |
-| `doCount(query, callback)` | Count matching records |
+```javascript
+let tmpQuery = _Fable.DAL.Book.query
+	.addFilter('Genre', 'Science Fiction')
+	.setCap(25)
+	.setBegin(0);
 
-## Query Building
+_Fable.DAL.Book.doReads(tmpQuery,
+	(pError, pQuery, pRecords) =>
+	{
+		console.log(`Found ${pRecords.length} sci-fi books`);
+	});
+```
 
-Each DAL has a `query` property (a FoxHound query instance) that you can configure with filters, sorting, and pagination:
+### Read with Sorting
 
 ```javascript
-// Read all Science Fiction books, newest first, page 1
 let tmpQuery = _Fable.DAL.Book.query
-    .addFilter('Genre', 'Science Fiction')
-    .addSort({Column: 'PublicationYear', Direction: 'Descending'})
-    .setCap(25)
-    .setBegin(0);
+	.addSort({ Column: 'PublicationYear', Direction: 'Descending' })
+	.setCap(10);
 
 _Fable.DAL.Book.doReads(tmpQuery,
-    (pError, pQuery, pRecords) =>
-    {
-        console.log(`Found ${pRecords.length} books`);
-    });
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Newest books:', pRecords);
+	});
 ```
 
-## Creating Records
+### Read with LIKE Filter
 
 ```javascript
-let tmpQuery = _Fable.DAL.Author.query
-    .addRecord({Name: 'Frank Herbert'});
-
-_Fable.DAL.Author.doCreate(tmpQuery,
-    (pError, pCreateQuery, pReadQuery, pRecord) =>
-    {
-        console.log('Created author with ID:', pRecord.IDAuthor);
-    });
+let tmpQuery = _Fable.DAL.Book.query
+	.addFilter('Title', '%Dune%', 'LIKE');
+
+_Fable.DAL.Book.doReads(tmpQuery,
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Dune books:', pRecords.length);
+	});
 ```
 
-## Counting Records
+## Count
 
 ```javascript
-let tmpQuery = _Fable.DAL.Review.query;
+let tmpQuery = _Fable.DAL.Book.query
+	.addFilter('Genre', 'Fantasy');
 
-_Fable.DAL.Review.doCount(tmpQuery,
-    (pError, pQuery, pCount) =>
-    {
-        console.log('Total reviews:', pCount);
-    });
+_Fable.DAL.Book.doCount(tmpQuery,
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Fantasy books:', pCount);
+	});
 ```
 
-## When to Use DAL vs Endpoints
+## Create
+
+```javascript
+let tmpQuery = _Fable.DAL.Book.query
+	.addRecord(
+	{
+		Title: 'Neuromancer',
+		Genre: 'Science Fiction',
+		PublicationYear: 1984
+	});
+
+_Fable.DAL.Book.doCreate(tmpQuery,
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Created book ID:', pRecord.IDBook);
+	});
+```
 
-Use the **REST endpoints** when:
-- Building a web UI that communicates over HTTP
-- Exposing an API for external consumers
-- You need session management and authorization
+## Update
 
-Use **DAL access** when:
-- Running server-side business logic
-- Performing batch operations
-- Writing behavior injection hooks that need to query related entities
-- Running background tasks or workers
+```javascript
+let tmpQuery = _Fable.DAL.Book.query
+	.addRecord(
+	{
+		IDBook: 42,
+		Title: 'Updated Title'
+	});
+
+_Fable.DAL.Book.doUpdate(tmpQuery,
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Updated:', pRecord.Title);
+	});
+```
+
+## Delete
+
+```javascript
+let tmpQuery = _Fable.DAL.Book.query
+	.addFilter('IDBook', 42);
+
+_Fable.DAL.Book.doDelete(tmpQuery,
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Deleted:', pResult);
+	});
+```
+
+## Cross-Entity Queries
+
+Use the DAL to query across entities:
+
+```javascript
+// Find authors for a book
+_Fable.DAL.BookAuthorJoin.doReads(
+	_Fable.DAL.BookAuthorJoin.query.addFilter('IDBook', 42),
+	(pError, pQuery, pJoins) =>
+	{
+		pJoins.forEach(
+			(pJoin) =>
+			{
+				_Fable.DAL.Author.doRead(
+					_Fable.DAL.Author.query.addFilter('IDAuthor', pJoin.IDAuthor),
+					(pError, pQuery, pAuthor) =>
+					{
+						console.log('Author:', pAuthor.Name);
+					});
+			});
+	});
+```
+
+## Query Object
+
+The query object is provided by FoxHound and supports method chaining:
+
+| Method | Description |
+|--------|-------------|
+| `addFilter(column, value, operator)` | Add a filter condition (default operator: `=`) |
+| `addSort({ Column, Direction })` | Add sort order (`Ascending` or `Descending`) |
+| `setCap(n)` | Limit result count |
+| `setBegin(n)` | Skip first N results |
+| `addRecord(object)` | Set record data for create/update |

package/docs/index.html

@@ -9,7 +9,7 @@
 		<title>Documentation</title>
 
 		<!-- Application Stylesheet -->
-		<link href="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/css/docuserve.css" rel="stylesheet">
+		<link href="css/docuserve.css" rel="stylesheet">
 		<!-- KaTeX stylesheet for LaTeX equation rendering -->
 		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
 		<!-- PICT Dynamic View CSS Container -->

package/docs/quick-start.md

@@ -0,0 +1,169 @@
+# Quick Start
+
+## Installation
+
+```bash
+npm install retold-data-service
+```
+
+You will also need a compiled Stricture schema (`MeadowModel-Extended.json`) for your data model.  See the [Schema Definition](schema-definition.md) guide for details on creating one.
+
+## MySQL Quick Start
+
+This example creates a Retold Data Service backed by MySQL:
+
+```javascript
+const libFable = require('fable');
+const libRetoldDataService = require('retold-data-service');
+
+// 1. Create a Fable instance with MySQL configuration
+let tmpSettings = (
+	{
+		Product: 'BookStoreAPI',
+		ProductVersion: '1.0.0',
+		APIServerPort: 8086,
+		MySQL:
+			{
+				Server: '127.0.0.1',
+				Port: 3306,
+				User: 'root',
+				Password: '',
+				Database: 'bookstore',
+				ConnectionPoolLimit: 20
+			},
+		MeadowConnectionMySQLAutoConnect: true
+	});
+
+let _Fable = new libFable(tmpSettings);
+
+// 2. Register the RetoldDataService service type
+_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
+
+// 3. Instantiate the service with options pointing to your compiled schema
+let _DataService = _Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
+	{
+		FullMeadowSchemaPath: `${__dirname}/model/`,
+		FullMeadowSchemaFilename: 'MeadowModel-Extended.json',
+		StorageProvider: 'MySQL',
+		StorageProviderModule: 'meadow-connection-mysql',
+		AutoStartOrator: true
+	});
+
+// 4. Initialize the service -- this starts the web server and creates all endpoints
+_DataService.initializeService(
+	(pError) =>
+	{
+		if (pError)
+		{
+			return console.error('Startup failed:', pError);
+		}
+		console.log('Data service running on port 8086');
+	});
+```
+
+## SQLite Quick Start
+
+For embedded use, testing, or rapid prototyping, use SQLite with an in-memory database:
+
+```javascript
+const libFable = require('fable');
+const libRetoldDataService = require('retold-data-service');
+const libMeadowConnectionSQLite = require('meadow-connection-sqlite');
+
+let tmpSettings = (
+	{
+		Product: 'BookStoreTest',
+		ProductVersion: '1.0.0',
+		APIServerPort: 9329,
+		SQLite:
+			{
+				SQLiteFilePath: ':memory:'
+			}
+	});
+
+let _Fable = new libFable(tmpSettings);
+
+// Register and connect the SQLite provider before initializing the data service
+_Fable.serviceManager.addServiceType('MeadowSQLiteProvider', libMeadowConnectionSQLite);
+_Fable.serviceManager.instantiateServiceProvider('MeadowSQLiteProvider');
+
+_Fable.MeadowSQLiteProvider.connectAsync(
+	(pError) =>
+	{
+		if (pError)
+		{
+			return console.error('SQLite connection failed:', pError);
+		}
+
+		// Register and instantiate the data service with SQLite options
+		_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
+		let _DataService = _Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
+			{
+				FullMeadowSchemaPath: `${__dirname}/model/`,
+				FullMeadowSchemaFilename: 'MeadowModel-Extended.json',
+				StorageProvider: 'SQLite',
+				StorageProviderModule: 'meadow-connection-sqlite',
+				AutoStartOrator: true
+			});
+
+		_DataService.initializeService(
+			(pError) =>
+			{
+				if (pError)
+				{
+					return console.error('Startup failed:', pError);
+				}
+				console.log('Data service running with in-memory SQLite');
+			});
+	});
+```
+
+> **Note:** For SQLite you need to install `meadow-connection-sqlite` as a dependency:
+> ```bash
+> npm install meadow-connection-sqlite
+> ```
+
+## What Happens
+
+After `initializeService` completes, the following are available:
+
+- **REST API** listening on the configured port (default `8086`)
+- **`fable.DAL.<Entity>`** for each entity in your Stricture schema -- direct data access layer objects for programmatic queries
+- **`fable.MeadowEndpoints.<Entity>`** for each entity -- endpoint controllers with behavior injection support
+- **8 CRUD endpoints per entity**, automatically mapped:
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `1.0/<Entity>/<ID>` | Read a single record by ID |
+| GET | `1.0/<Entities>` | Read all records |
+| GET | `1.0/<Entities>/<Begin>/<Cap>` | Read records with pagination |
+| GET | `1.0/<Entities>/FilteredTo/<Filter>` | Read records matching a filter |
+| GET | `1.0/<Entities>/Count` | Count all records |
+| POST | `1.0/<Entity>` | Create a new record |
+| PUT | `1.0/<Entity>` | Update an existing record |
+| DELETE | `1.0/<Entity>/<ID>` | Soft-delete a record |
+
+Additional endpoints include schema introspection (`GET 1.0/<Entity>/Schema`) and default record generation (`GET 1.0/<Entity>/Schema/New`).
+
+## Verify It Works
+
+Once the service is running, test it with curl:
+
+```bash
+# Read all Books (paginated, first 10)
+curl http://localhost:8086/1.0/Books/0/10
+
+# Read a single Book by ID
+curl http://localhost:8086/1.0/Book/1
+
+# Count all Books
+curl http://localhost:8086/1.0/Books/Count
+
+# Get the schema for Book
+curl http://localhost:8086/1.0/Book/Schema
+
+# Create a new Book
+curl -X POST http://localhost:8086/1.0/Book \
+	-H "Content-Type: application/json" \
+	-d '{"Title": "Dune", "Genre": "Science Fiction", "PublicationYear": 1965}'
+```

package/docs/retold-catalog.json

@@ -0,0 +1,144 @@
+{
+	"Generated": "2026-03-02T03:24:01.334Z",
+	"GitHubOrg": "stevenvelozo",
+	"DefaultBranch": "master",
+	"Groups": [
+		{
+			"Name": ".config",
+			"Key": ".config",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "code-server",
+					"Repo": "code-server",
+					"Group": ".config",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "configstore",
+					"Repo": "configstore",
+					"Group": ".config",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "luxury-extras",
+					"Repo": "luxury-extras",
+					"Group": ".config",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "vscode-sqltools",
+					"Repo": "vscode-sqltools",
+					"Group": ".config",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Debug",
+			"Key": "debug",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "data",
+					"Repo": "data",
+					"Group": "debug",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Dist",
+			"Key": "dist",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "indoctrinate_content_staging",
+					"Repo": "indoctrinate_content_staging",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Docs",
+			"Key": "docs",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "api",
+					"Repo": "api",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"api/constructor.md",
+						"api/initializeDataEndpoints.md",
+						"api/initializePersistenceEngine.md",
+						"api/initializeService.md",
+						"api/onAfterInitialize.md",
+						"api/onBeforeInitialize.md",
+						"api/onInitialize.md",
+						"api/reference.md",
+						"api/stopService.md"
+					]
+				},
+				{
+					"Name": "css",
+					"Repo": "css",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"css/docuserve.css"
+					]
+				}
+			]
+		},
+		{
+			"Name": "Test",
+			"Key": "test",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "model",
+					"Repo": "model",
+					"Group": "test",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		}
+	]
+}