masterrecord 0.2.1 → 0.2.3

package/Migrations/cli.js

@@ -9,6 +9,7 @@ let fs = require('fs');
 let path = require('path');
 var Migration = require('./migrations');
 var globSearch = require("glob");
+const pkg = require(path.join(__dirname, '..', 'package.json'));
 
 
 const [,, ...args] = process.argv
@@ -16,9 +17,12 @@ const [,, ...args] = process.argv
 
 
 program
-  .version('0.0.3')
+  .version(pkg.version, '-v, --version')
   .description('A ORM framework that facilitates the creation and use of business objects whose data requires persistent storage to a database');
 
+// Support legacy '-V' as an alias to print version
+program.option('-V', 'output the version');
+
   // Instructions : to run command you must go to main project folder is located and run the command using the context file name.
   program
   .command('enable-migrations <contextFileName>')
@@ -275,4 +279,10 @@ program
 
 
 
-program.parse(process.argv);
+program.parse(process.argv);
+
+// Handle manual '-V' alias
+const opts = program.opts();
+if (opts && opts.V) {
+  console.log(pkg.version);
+}

package/package.json

@@ -8,7 +8,7 @@
     "sync-mysql2" : "^1.0.6",
     "app-root-path": "^3.1.0"
   },
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "An Object-relational mapping for the Master framework. Master Record connects classes to relational database tables to establish a database with almost zero-configuration ",
   "homepage": "https://github.com/Tailor/MasterRecord#readme",
   "repository": {
@@ -22,6 +22,6 @@
   "author": "Alexander Rich",
   "license": "ISC",
   "bin": {
-    "masterrecord": "./migrations/cli.js"
+    "masterrecord": "./Migrations/cli.js"
   }
 }

package/readme.md

@@ -1,3 +1,182 @@
-local install of CLI package run code in terminal - "npm install -g ./" master
 
-For full instructions on running migrations and updating the server, see `MIGRATIONS.md`.
+
+# MasterRecord
+
+MasterRecord is a lightweight, code-first ORM and migration tool for Node.js with a fluent query API. It lets you define entities in JavaScript, generate migrations, and query with expressive syntax.
+
+- Supported databases: MySQL, SQLite
+- Synchronous API by default (no await needed)
+- Built-in CLI for migrations and seeding
+
+## Installation
+
+```bash
+# npm
+npm install masterrecord
+
+# pnpm
+pnpm add masterrecord
+
+# yarn
+yarn add masterrecord
+```
+
+## Quick Start
+
+1) Create an environment config file (see Environment below), then enable migrations:
+
+```bash
+npx masterrecord enable-migrations AppContext
+```
+
+2) Make or change your entities, then create a migration file:
+
+```bash
+npx masterrecord add-migration Init AppContext
+```
+
+3) Apply the migration to your database:
+
+```bash
+master=development npx masterrecord update-database AppContext
+```
+
+### Enable migrations (one-time per Context)
+
+- Run from the project root where your Context file lives. Use the Context file name (without extension) as the argument.
+```bash
+master=development masterrecord enable-migrations AppContext
+```
+This creates `db/migrations/<context>_contextSnapShot.json` and the `db/migrations` directory.
+
+### Create a migration
+
+- After you change your entity models, generate a migration file:
+```bash
+master=development masterrecord add-migration <MigrationName> AppContext
+```
+This writes a new file to `db/migrations/<timestamp>_<MigrationName>_migration.js`.
+
+###  Apply migrations to the database
+
+- Apply only the latest pending migration:
+```bash
+master=development masterrecord update-database AppContext
+```
+- Apply all migrations from the beginning (useful for a clean DB):
+```bash
+master=development masterrecord update-database-restart AppContext
+```
+- List migration files (debug/inspection):
+```bash
+master=development masterrecord get-migrations AppContext
+```
+
+Notes:
+- The CLI searches for `<context>_contextSnapShot.json` under `db/migrations` relative to your current working directory.
+- For MySQL, ensure your credentials allow DDL. For SQLite, the data directory is created if missing.
+
+### Updating the running server
+
+General flow to roll out schema changes:
+- Stop the server or put it into maintenance mode (optional but recommended for non-backward-compatible changes).
+- Pull the latest code (containing updated models and generated migration files).
+- Run migrations against the target environment:
+```bash
+master=production masterrecord update-database AppContext
+```
+- Restart your server/process manager (e.g., `pm2 restart <app>`, `docker compose up -d`, or your platform’s restart command).
+
+Backward-compatible rollout tip:
+- If possible, deploy additive changes first (new tables/columns), release app code that begins using them, then later clean up/removal migrations.
+
+### Troubleshooting
+
+- Cannot find Context file: ensure you run commands from the app root and pass the correct Context file name used when defining your class (case-insensitive in the snapshot, but supply the same name you used).
+- Cannot connect to DB: confirm `master=<env>` is set and `env.<env>.json` exists with correct credentials and paths.
+- MySQL type mismatches: the migration engine maps MasterRecord types to SQL types; verify your entity field `type` values are correct.
+
+### Recent improvements (2025-09)
+
+- Query language and SQL engines:
+  - Correct parsing of multi-char operators (>=, <=, ===, !==) and spaced logical operators.
+  - Support for grouped OR conditions rendered as parenthesized OR in WHERE across SQLite/MySQL.
+  - Resilient fallback for partially parsed expressions.
+- Relationships:
+  - `hasManyThrough` supported in insert and delete cascades.
+- Environment file discovery:
+  - Context now walks up directories to find `config/environments/env.<env>.json`; fixed error throwing.
+- Migrations (DDL generation):
+  - Default values emitted for SQLite/MySQL (including boolean coercion).
+  - `CREATE TABLE IF NOT EXISTS` to avoid failures when rerunning.
+  - Table introspection added; existing tables are synced: missing columns are added, MySQL applies `ALTER ... MODIFY` for NULL/DEFAULT changes, SQLite rebuilds table when necessary.
+- Migration API additions in `schema.js`:
+  - `renameColumn(table)` implemented for SQLite/MySQL.
+  - `seed(tableName, rows)` implemented for bulk/single inserts with safe quoting.
+
+### Using renameColumn and seed in migrations
+
+Basic migration skeleton (generated by CLI):
+```js
+var masterrecord = require('masterrecord');
+
+class AddSettings extends masterrecord.schema { 
+  constructor(context){ super(context); }
+
+  up(table){
+    this.init(table);
+    // Add a new table
+    this.createTable(table.MailSettings);
+
+    // Rename a column on an existing table
+    this.renameColumn({ tableName: 'MailSettings', name: 'from_email', newName: 'reply_to' });
+
+    // Seed initial data (single row)
+    this.seed('MailSettings', {
+      from_name: 'System',
+      reply_to: 'no-reply@example.com',
+      return_path_matches_from: 0,
+      weekly_summary_enabled: 0,
+      created_at: Date.now(),
+      updated_at: Date.now()
+    });
+
+    // Seed multiple rows
+    this.seed('MailSettings', [
+      { from_name: 'Support', reply_to: 'support@example.com', created_at: Date.now(), updated_at: Date.now() },
+      { from_name: 'Marketing', reply_to: 'marketing@example.com', created_at: Date.now(), updated_at: Date.now() }
+    ]);
+  }
+
+  down(table){
+    this.init(table);
+    // Revert the rename
+    this.renameColumn({ tableName: 'MailSettings', name: 'reply_to', newName: 'from_email' });
+
+    // Optionally clean up seeded rows
+    // this.context._execute("DELETE FROM MailSettings WHERE reply_to IN ('no-reply@example.com','support@example.com','marketing@example.com')");
+
+    // Drop table if that was part of up
+    // this.dropTable(table.MailSettings);
+  }
+}
+module.exports = AddSettings;
+```
+
+Notes:
+- `renameColumn` expects an object: `{ tableName, name, newName }` and works in both SQLite and MySQL.
+- `seed(tableName, rows)` accepts:
+  - a single object: `{ col: value, ... }`
+  - or an array of objects: `[{...}, {...}]`
+  Values are auto-quoted; booleans become 1/0.
+- When a table already exists, `update-database` will sync schema:
+  - Add missing columns.
+  - MySQL: adjust default/nullability via `ALTER ... MODIFY`.
+  - SQLite: rebuilds the table when nullability/default/type changes require it.
+
+### Tips
+- Prefer additive changes (add columns) before destructive changes (drops/renames) to minimize downtime.
+- For large SQLite tables, a rebuild copies data; consider maintenance windows.
+- Use `master=development masterrecord get-migrations AppContext` to inspect migration order.
+
+

package/MIGRATIONS.md

@@ -1,178 +0,0 @@
-### Migrations and Server Update Guide
-
-This project ships a CLI, exposed as `masterrecord`, to manage database migrations. Below are the steps to enable migrations, create migrations, apply them, and update your running server.
-
-### 1) Install the CLI (local repo checkout)
-
-- From the project root, install the CLI globally:
-```bash
-npm install -g ./
-```
-
-After install, the `masterrecord` command becomes available in your shell.
-
-### 2) Prepare your Context and Environment
-
-- Ensure your app has a Context class that extends `context` and configures a DB connection (SQLite or MySQL) using either `useSqlite()` or `useMySql()`.
-- Set the environment via the `master` env var when running commands, e.g. `master=development` or `master=production`.
-- Provide environment JSON at `env.<ENV>.json` reachable from your app root, keyed by your Context class name. Example for SQLite:
-```json
-{
-  "AppContext": {
-    "type": "better-sqlite3",
-    "connection": "/db/app.sqlite"
-  }
-}
-```
-Example for MySQL:
-```json
-{
-  "AppContext": {
-    "type": "mysql",
-    "host": "localhost",
-    "user": "root",
-    "password": "secret",
-    "database": "app_db"
-  }
-}
-```
-
-### 3) Enable migrations (one-time per Context)
-
-- Run from the project root where your Context file lives. Use the Context file name (without extension) as the argument.
-```bash
-master=development masterrecord enable-migrations AppContext
-```
-This creates `db/migrations/<context>_contextSnapShot.json` and the `db/migrations` directory.
-
-### 4) Create a migration
-
-- After you change your entity models, generate a migration file:
-```bash
-master=development masterrecord add-migration <MigrationName> AppContext
-```
-This writes a new file to `db/migrations/<timestamp>_<MigrationName>_migration.js`.
-
-### 5) Apply migrations to the database
-
-- Apply only the latest pending migration:
-```bash
-master=development masterrecord update-database AppContext
-```
-- Apply all migrations from the beginning (useful for a clean DB):
-```bash
-master=development masterrecord update-database-restart AppContext
-```
-- List migration files (debug/inspection):
-```bash
-master=development masterrecord get-migrations AppContext
-```
-
-Notes:
-- The CLI searches for `<context>_contextSnapShot.json` under `db/migrations` relative to your current working directory.
-- For MySQL, ensure your credentials allow DDL. For SQLite, the data directory is created if missing.
-
-### 6) Updating the running server
-
-General flow to roll out schema changes:
-- Stop the server or put it into maintenance mode (optional but recommended for non-backward-compatible changes).
-- Pull the latest code (containing updated models and generated migration files).
-- Run migrations against the target environment:
-```bash
-master=production masterrecord update-database AppContext
-```
-- Restart your server/process manager (e.g., `pm2 restart <app>`, `docker compose up -d`, or your platform’s restart command).
-
-Backward-compatible rollout tip:
-- If possible, deploy additive changes first (new tables/columns), release app code that begins using them, then later clean up/removal migrations.
-
-### Troubleshooting
-
-- Cannot find Context file: ensure you run commands from the app root and pass the correct Context file name used when defining your class (case-insensitive in the snapshot, but supply the same name you used).
-- Cannot connect to DB: confirm `master=<env>` is set and `env.<env>.json` exists with correct credentials and paths.
-- MySQL type mismatches: the migration engine maps MasterRecord types to SQL types; verify your entity field `type` values are correct.
-
-### Recent improvements (2025-09)
-
-- Query language and SQL engines:
-  - Correct parsing of multi-char operators (>=, <=, ===, !==) and spaced logical operators.
-  - Support for grouped OR conditions rendered as parenthesized OR in WHERE across SQLite/MySQL.
-  - Resilient fallback for partially parsed expressions.
-- Relationships:
-  - `hasManyThrough` supported in insert and delete cascades.
-- Environment file discovery:
-  - Context now walks up directories to find `config/environments/env.<env>.json`; fixed error throwing.
-- Migrations (DDL generation):
-  - Default values emitted for SQLite/MySQL (including boolean coercion).
-  - `CREATE TABLE IF NOT EXISTS` to avoid failures when rerunning.
-  - Table introspection added; existing tables are synced: missing columns are added, MySQL applies `ALTER ... MODIFY` for NULL/DEFAULT changes, SQLite rebuilds table when necessary.
-- Migration API additions in `schema.js`:
-  - `renameColumn(table)` implemented for SQLite/MySQL.
-  - `seed(tableName, rows)` implemented for bulk/single inserts with safe quoting.
-
-### Using renameColumn and seed in migrations
-
-Basic migration skeleton (generated by CLI):
-```js
-var masterrecord = require('masterrecord');
-
-class AddSettings extends masterrecord.schema { 
-  constructor(context){ super(context); }
-
-  up(table){
-    this.init(table);
-    // Add a new table
-    this.createTable(table.MailSettings);
-
-    // Rename a column on an existing table
-    this.renameColumn({ tableName: 'MailSettings', name: 'from_email', newName: 'reply_to' });
-
-    // Seed initial data (single row)
-    this.seed('MailSettings', {
-      from_name: 'System',
-      reply_to: 'no-reply@example.com',
-      return_path_matches_from: 0,
-      weekly_summary_enabled: 0,
-      created_at: Date.now(),
-      updated_at: Date.now()
-    });
-
-    // Seed multiple rows
-    this.seed('MailSettings', [
-      { from_name: 'Support', reply_to: 'support@example.com', created_at: Date.now(), updated_at: Date.now() },
-      { from_name: 'Marketing', reply_to: 'marketing@example.com', created_at: Date.now(), updated_at: Date.now() }
-    ]);
-  }
-
-  down(table){
-    this.init(table);
-    // Revert the rename
-    this.renameColumn({ tableName: 'MailSettings', name: 'reply_to', newName: 'from_email' });
-
-    // Optionally clean up seeded rows
-    // this.context._execute("DELETE FROM MailSettings WHERE reply_to IN ('no-reply@example.com','support@example.com','marketing@example.com')");
-
-    // Drop table if that was part of up
-    // this.dropTable(table.MailSettings);
-  }
-}
-module.exports = AddSettings;
-```
-
-Notes:
-- `renameColumn` expects an object: `{ tableName, name, newName }` and works in both SQLite and MySQL.
-- `seed(tableName, rows)` accepts:
-  - a single object: `{ col: value, ... }`
-  - or an array of objects: `[{...}, {...}]`
-  Values are auto-quoted; booleans become 1/0.
-- When a table already exists, `update-database` will sync schema:
-  - Add missing columns.
-  - MySQL: adjust default/nullability via `ALTER ... MODIFY`.
-  - SQLite: rebuilds the table when nullability/default/type changes require it.
-
-### Tips
-- Prefer additive changes (add columns) before destructive changes (drops/renames) to minimize downtime.
-- For large SQLite tables, a rebuild copies data; consider maintenance windows.
-- Use `master=development masterrecord get-migrations AppContext` to inspect migration order.
-
-