meadow-endpoints 4.0.5 → 4.0.9

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Retold
+
+We welcome contributions to Retold and its modules. This guide covers the expectations and process for contributing.
+
+## Code of Conduct
+
+The Retold community values **empathy**, **equity**, **kindness**, and **thoughtfulness**. We expect all participants to treat each other with respect, assume good intent, and engage constructively. These values apply to all interactions: pull requests, issues, discussions, and code review.
+
+## How to Contribute
+
+### Pull Requests
+
+Pull requests are the preferred method for contributing changes. To submit one:
+
+1. Fork the module repository you want to change
+2. Create a branch for your work
+3. Make your changes, following the code style of the module you are editing
+4. Ensure your changes have test coverage (see below)
+5. Open a pull request against the module's main branch
+
+**Submitting a pull request does not guarantee it will be accepted.** Maintainers review contributions for fit, quality, and alignment with the project's direction. A PR may be declined, or you may be asked to revise it. This is normal and not a reflection on the quality of your effort.
+
+### Reporting Issues
+
+If you find a bug or have a feature suggestion, open an issue on the relevant module's repository. Include enough detail to reproduce the problem or understand the proposal.
+
+## Test Coverage
+
+Every commit must include test coverage for the changes it introduces. Retold modules use Mocha in TDD style. Before submitting:
+
+- **Write tests** for any new functionality or bug fixes
+- **Run the existing test suite** with `npm test` and confirm all tests pass
+- **Check coverage** with `npm run coverage` if the module supports it
+
+Pull requests that break existing tests or lack coverage for new code will not be merged.
+
+## Code Style
+
+Follow the conventions of the module you are working in. The general Retold style is:
+
+- **Tabs** for indentation, never spaces
+- **Plain JavaScript** only (no TypeScript)
+- **Allman-style braces** (opening brace on its own line)
+- **Variable naming:** `pVariable` for parameters, `tmpVariable` for temporaries, `libSomething` for imports
+
+When in doubt, match what the surrounding code does.
+
+## Repository Structure
+
+Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/Dockerfile_LUXURYCode

@@ -16,44 +16,6 @@ RUN echo "Building RETOLD development image..."
 RUN echo "...installing vscode extensions..."
 
 # Mocha unit testing in the sidebar
-RUN code-server --install-extension hbenl.vscode-mocha-test-adapter
-RUN code-server --install-extension hbenl.test-adapter-converter
-RUN code-server --install-extension hbenl.vscode-test-explorer
-
-# Magic indentation rainbow
-RUN code-server --install-extension oderwat.indent-rainbow
-RUN code-server --install-extension dbaeumer.vscode-eslint
-
-# Contextual git
-RUN code-server --install-extension eamodio.gitlens
-
-# Other extensions (uncomment them to have them automagic, or run this from a terminal to install in the container):
-
-# SQL Tools
-RUN code-server --install-extension mtxr.sqltools
-RUN code-server --install-extension mtxr.sqltools-driver-mysql
-
-# Microsoft's AI code completion
-# RUN code-server --install-extension  VisualStudioExptTeam.vscodeintellicode
-
-# Live server -- make sure to open up the port on the docker image
-# RUN code-server --install-extension ritwickdey.LiveServer
-
-# Quick link to required modules' documentation
-RUN code-server --install-extension bengreenier.vscode-node-readme
-
-# Switch up fonts
-# RUN code-server --install-extension evan-buss.font-switcher
-
-# Icons
-# RUN code-server --install-extension vscode-icons-team.vscode-icons
-# RUN code-server --install-extension PKief.material-icon-theme
-
-# Hover over CSS colors to see them previewed
-# RUN code-server --install-extension bierner.color-info
-
-# An easy on the eyes color theme
-# RUN code-server --install-extension daylerees.rainglow
 
 RUN echo "...configuring mariadb (mysql) server..."
 RUN sudo sed -i "s|bind-address|#bind-address|g" /etc/mysql/mariadb.conf.d/50-server.cnf
@@ -87,4 +49,4 @@ RUN . ~/.nvm/nvm.sh && source ~/.bashrc && nvm alias default 14
 
 WORKDIR /home/coder/meadow-endpoints
 
-ENTRYPOINT ["/usr/bin/MySQL-Laden-Entry.sh"]
+ENTRYPOINT ["/usr/bin/MySQL-Laden-Entry.sh"]

package/README.md

@@ -1,82 +1,203 @@
 # Meadow Endpoints
 
-Automagic REST endpoints for basic CRUD operations on the Retold framework.
-
-This library generates REST endpoints in a consistent manner.  Endpoints have the following features:
-
-* Authentication
-* Resource Authorization
-* CRUD Operations
-* Dynamic Filtering
-* Schema Validation
-
-The design philosophy is not to cover every possible use case, but to cover the 99% via configuration.  The last 1% is easily hand-craftable.
+> Automagic REST endpoints for CRUD operations on the Retold framework
+
+Meadow Endpoints generates a full suite of RESTful API routes from your Meadow data entities. Define your data model with Meadow, point Meadow Endpoints at it, and you get Create, Read, Update, Delete, Count, Schema, and Validate endpoints -- with authentication hooks, authorization, dynamic filtering, pagination, and behavior injection for customization. The design philosophy is to cover the 99% via configuration; the last 1% is easily hand-craftable.
+
+## Features
+
+- **Automatic Route Generation** - Full CRUD endpoints from a Meadow entity with zero boilerplate
+- **Behavior Injection** - Pre/post operation hooks for authentication, authorization, and custom logic
+- **Dynamic Filtering** - URL-based filter expressions for flexible querying
+- **Pagination** - Built-in Begin/Cap parameters with configurable default limits
+- **Bulk Operations** - Batch create, update, and upsert endpoints
+- **Schema Endpoints** - Serve JSON Schema, default objects, and validation
+- **Controller Architecture** - Extensible controller system with replaceable error handling, logging, and session management
+- **Fable Integration** - First-class service in the Fable/Orator ecosystem
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libMeadow = require('meadow');
+const libMeadowEndpoints = require('meadow-endpoints');
+
+const _Fable = new libFable({
+	Product: 'MyAPI',
+	ProductVersion: '1.0.0',
+	ServicePort: 8086
+});
+
+// Set up Orator
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Create a Meadow DAL for "Book"
+const tmpMeadow = libMeadow.new(_Fable, '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: 'CreateDate', Type: 'CreateDate' },
+		{ Column: 'CreatingIDUser', Type: 'CreateIDUser' },
+		{ Column: 'UpdateDate', Type: 'UpdateDate' },
+		{ Column: 'UpdatingIDUser', Type: 'UpdateIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// Generate and connect endpoints
+const tmpMeadowEndpoints = new libMeadowEndpoints(tmpMeadow);
+tmpMeadowEndpoints.connectRoutes(_Fable.Orator.serviceServer);
+
+// Start the server
+_Fable.Orator.startService(() =>
+{
+	console.log('API running on port 8086');
+	// GET    /1.0/Book/:IDBook       - Read one
+	// GET    /1.0/Book/s/:Begin/:Cap - Read many
+	// POST   /1.0/Book               - Create
+	// PUT    /1.0/Book               - Update
+	// DELETE /1.0/Book/:IDBook       - Delete
+	// GET    /1.0/Book/s/Count       - Count
+	// GET    /1.0/Book/Schema        - Schema
+});
+```
 
-To best use this library, it should be in conjunction with [stricture](https://github.com/stevenvelozo/stricture) and [orator](https://github.com/stevenvelozo/orator).
+## Installation
 
+```bash
+npm install meadow-endpoints
+```
 
-### Docker Development Environment
+## How It Works
 
-1. Run this command to build this image:
+Meadow Endpoints takes a configured Meadow DAL instance and registers HTTP routes with an Orator service server. Each route follows an async waterfall pattern with behavior injection points for customization.
 
 ```
-npm run docker-dev-build-image
+Orator (API Server)
+  └── Meadow Endpoints (Route Registration)
+        ├── Controller (Request Lifecycle)
+        │     ├── Session Marshaler
+        │     ├── Behavior Injection
+        │     ├── Error Handler
+        │     └── Log Controller
+        └── Meadow DAL (Data Access)
+              └── Database Provider
 ```
 
-2. Run this command to create and run the local container:
+## Generated Routes
 
-```
-npm run docker-dev-run
-```
+### CRUD
 
-3. Go to http://localhost:12343/ in a web browser
+| Method | Route | Description |
+|--------|-------|-------------|
+| POST | `/{ver}/{entity}` | Create a record |
+| POST | `/{ver}/{entity}/s` | Bulk create |
+| GET | `/{ver}/{entity}/:ID` | Read one record |
+| GET | `/{ver}/{entity}/s/:Begin/:Cap` | Read many with pagination |
+| GET | `/{ver}/{entity}/s/FilteredTo/:Filter` | Read with filter |
+| PUT | `/{ver}/{entity}` | Update a record |
+| PUT | `/{ver}/{entity}/Upsert` | Insert or update |
+| DELETE | `/{ver}/{entity}/:ID` | Delete a record |
+| GET | `/{ver}/{entity}/Undelete/:ID` | Undelete a record |
+| GET | `/{ver}/{entity}/s/Count` | Count records |
 
-4. The password is "retold"
+### Specialized Read
 
-5. Right now you (may) need to delete the `node_modules` folders and regenerate it for Linux, depending on your OS.
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{ver}/{entity}/Select` | Select list ({Hash, Value} pairs) |
+| GET | `/{ver}/{entity}/s/Lite` | Lite list (minimal columns) |
+| GET | `/{ver}/{entity}/s/Distinct/:Columns` | Distinct values |
+| GET | `/{ver}/{entity}/Max/:Column` | Maximum value |
 
+### Schema
 
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{ver}/{entity}/Schema` | JSON Schema |
+| GET | `/{ver}/{entity}/Schema/New` | Empty default record |
+| POST | `/{ver}/{entity}/Schema/Validate` | Validate a record |
 
-## Pattern Description to Expand
+## Behavior Injection
 
-```
-const libMeadowEndpointsControllerBase = require('meadow-endpoints').ControllerBase;
+Hook into any endpoint's lifecycle for authorization and custom logic:
 
-class MySpecialLogController inherits libMeadowEndpointsControllerBase.LogControllerBase
-{
-	constructor(pMeadowEndpoints, pOptions)
-	{
-		super(pMeadowEndpoints, pOptions);
-	}
+```javascript
+const tmpEndpoints = new libMeadowEndpoints(tmpMeadow);
 
-	// Overload info to do something special
-	info(pLogText, ...pLogObjects)
+// Add customer-scoped reads
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Reads-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
 	{
-		super(pLogText, ...pLogObjects);
-		console.log('### THIS CONTROLLER DO MAGIC STUFF WITH'+pLogText);
-	}
-}
+		pRequestState.Query.addFilter('IDCustomer', pRequestState.SessionData.CustomerID);
+		return fCallback();
+	});
+```
 
-class MyMeadowEndpointsController
-{
-	constructor(pMeadowEndpoints, pOptions)
-	{
-		super(pMeadowEndpoints, pOptions);
+### Injection Points
 
-		this._LogController = new mySpecialLogController(pMeadowEndpoints, pOptions);
+| Point | Phase |
+|-------|-------|
+| `Create-PreOperation` / `Create-PostOperation` | Before/after creation |
+| `Create-QueryConfiguration` | After query built, before execution |
+| `Read-PreOperation` / `Read-PostOperation` | Before/after single read |
+| `Reads-QueryConfiguration` / `Reads-PostOperation` | Multi-record reads |
+| `Update-QueryConfiguration` | After update query built |
+| `Delete-PreOperation` / `Delete-PostOperation` | Before/after deletion |
+| `Count-QueryConfiguration` | After count query built |
 
-		this.initializeDefaultUnsetControllers(pMeadowEndpoints, pControllerOptions);
-	}
-}
+## Dynamic Filtering
 
-module.exports = MyMeadowEndpointsController;
 ```
+GET /1.0/Book/s/FilteredTo/Title~JavaScript
+GET /1.0/Book/s/FilteredTo/Author=Frank Herbert
+GET /1.0/Book/s/FilteredTo/Price>20
+```
+
+Operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `~` (contains)
+
+## Configuration
 
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `MeadowEndpointVersion` | string | `"1.0"` | API version prefix |
+| `MeadowDefaultMaxCap` | number | `250` | Default pagination limit |
+| `MeadowEndpointsSessionDataSource` | string | `"Request"` | Session data source (`Request`, `Header`, `None`) |
+| `SendErrorStatusCodes` | boolean | `false` | Set HTTP status codes on errors |
+
+## Testing
+
+```bash
+npm test
 ```
-let libMySpecialController = require('TheCodeAbove.js');
 
-let tmpMeadow = new Meadow('INITIALIZE THE DAL');
+## Documentation
+
+Detailed documentation is available in the `docs/` folder and can be served locally:
+
+```bash
+npx docsify-cli serve docs
+```
+
+## Related Packages
+
+- [meadow](https://github.com/stevenvelozo/meadow) - Data access and ORM
+- [foxhound](https://github.com/stevenvelozo/foxhound) - Query DSL for SQL generation
+- [orator](https://github.com/stevenvelozo/orator) - API server abstraction
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+
+## License
+
+MIT
 
-let tmpMeadowEndpoints = new MeadowEndpoints(tmpMeadow, { Controller: libMySpecialController });
+## Contributing
 
-```
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).