fastify-auto-sqlapi 0.0.4 → 0.1.1

package/README.md

@@ -1,15 +1,16 @@
 # fastify-auto-sqlapi
 
-Automatic CRUD API generation from PostgreSQL tables for [Fastify](https://fastify.dev/). No ORM, no magic — just raw SQL via `pg`, with TypeBox validation and Swagger docs out of the box.
+Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fastify](https://fastify.dev/). No ORM, no magic — just raw SQL, with TypeBox validation and Swagger docs out of the box.
 
-Point it at your database, and get a full REST API with search, pagination, joins, bulk operations, multi-tenant isolation, and hooks.
+Point it at your database, and get a full REST API with search, advanced conditions, pagination, joins, aggregations, bulk operations, multi-tenant isolation, validation, and hooks.
 
 ## Features
 
 - **Zero boilerplate** — define your tables, get 7 endpoints each
 - **No ORM** — raw SQL via `pg` + parameterized queries
 - **TypeBox validation** — request/response schemas auto-generated from your DB
-- **Virtual joins** — fetch related records without complex SQL
+- **Joins** — four explicit families (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) with alias support
+- **Computed fields** — declare virtual fields as SQL expressions in `defineTable`; usable like schema fields in filters/orderBy/conditions, and opt-in projected in the response via `selectComputed`. Covers JSON extraction, derived columns, dialect-aware date bucketing
 - **Bulk operations** — batch insert/upsert/delete in single queries
 - **Multi-tenant** — automatic row-level isolation, zero code in handlers
 - **Validation** — structured field-level validation with cross-entity support
@@ -17,6 +18,8 @@ Point it at your database, and get a full REST API with search, pagination, join
 - **Swagger UI** — optional, auto-configured from your schemas
 - **Composable** — register all routes or pick only what you need
 
+> ⚠️ **Migrating from a previous version?** The join API was redesigned. See **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for the full migration guide.
+
 ## Quick Start
 
 ### 1. Install
@@ -143,12 +146,16 @@ const TableCustomer = defineTable({
   excludeFromCreation: ['id'],              // omit from INSERT (e.g. auto-increment)
   distinctResults: true,                    // SELECT DISTINCT
 
-  // Relations
+  // Relations — alias defaults to joinSchema.tableName. Override with `{ alias: '...' }`
+  // when you join the same table twice (e.g. `createdBy`/`updatedBy`) or want a friendlier
+  // name. Set `unique: true` for N:1 (parent) relations to enable `joinLeft`.
   allowedReadJoins: [
-    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),
+    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
+    buildRelation(SchemaSession, 'userId', SchemaUser, 'id', { unique: true }),           // alias = 'user', N:1
+    buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true }),
   ],
   allowedWriteJoins: [
-    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),
+    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
   ],
 
   // Upsert (ON CONFLICT)
@@ -176,10 +183,10 @@ const TableCustomer = defineTable({
     return [];
   },
 
-  // Hooks (runs after validation)
-  beforeInsert: async (db, req, record) => { /* record is snake_case */ },
-  beforeUpdate: async (db, req, fields) => { /* fields is snake_case */ },
-  afterInsert: async (db, req, record, secondaryRecords) => { /* record is camelCase */ },
+  // Hooks (runs after validation) — all receive camelCase records (schema field names)
+  beforeInsert: async (db, req, record) => { /* camelCase; mutations propagate to INSERT */ },
+  beforeUpdate: async (db, req, fields) => { /* camelCase; PK included for reference, excluded from UPDATE SET */ },
+  afterInsert: async (db, req, record, secondaryRecords) => { /* camelCase; input merged with generated PK */ },
 
   // Auth (per-table)
   onRequests: [
@@ -219,37 +226,89 @@ const TableCustomer = defineTable({
 ```typescript
 await app.register(fastifyAutoSqlApi, {
   DbTables: dbTables,           // Required — your table definitions
+  dialect: 'postgres',          // Optional — 'postgres' | 'mysql' | 'mariadb' (default: 'postgres')
   prefix: '/api',               // Optional — URL prefix for all routes
   swagger: true,                // Optional — enable Swagger UI (or pass SwaggerOptions)
   onRequests: [authMiddleware],  // Optional — global hooks applied to every route
   getTenantId: (req) => id,     // Optional — multi-tenant function
+  debug: true,                  // Optional — log all SQL queries and params
 });
 ```
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `DbTables` | `Record<string, ITable>` | Yes | Table configurations |
+| `dialect` | `'postgres' \| 'mysql' \| 'mariadb'` | No | DB dialect (default: `'postgres'`) |
 | `prefix` | `string` | No | URL prefix (e.g. `/api`) |
 | `swagger` | `boolean \| SwaggerOptions` | No | Enable Swagger UI |
 | `onRequests` | `Function[]` | No | Global auth/middleware hooks |
 | `getTenantId` | `(req) => id \| null` | No | Tenant resolver for multi-tenant |
+| `debug` | `boolean` | No | Log all SQL queries to console |
+
+For MySQL/MariaDB, register `mysql2/promise` pool instead of `@fastify/postgres` and pass `dialect: 'mysql'` or `'mariadb'`.
 
 ## API Reference
 
 ### POST /search/{table}
 
-Search with filters, pagination, ordering, joins, and aggregations.
+Search with filters, advanced conditions, pagination, ordering, joins, and aggregations.
 
 **Request body** (all fields optional):
 
 ```json
 {
   "filters": { "name": "Mario" },
-  "joins": { "order": {} },
-  "paginator": { "page": 1, "itemsPerPage": 20 }
+  "conditions": [
+    { "field": "total", "method": "isGreater", "params": [100] },
+    { "field": "createdAt", "method": "isBetween", "params": ["2024-01-01", "2024-12-31"] }
+  ],
+  "joinMustExist": {
+    "orders": {
+      "filters": { "status": "completed" },
+      "conditions": [{ "field": "total", "method": "isGreater", "params": [50] }]
+    }
+  },
+  "joinMultiple": {
+    "orders": {
+      "filters": { "status": "completed" },
+      "selection": "id,total,status"
+    }
+  },
+  "joinGroup": {
+    "orders": {
+      "aggregations": {
+        "by": "status",
+        "sum": ["total"],
+        "min": ["total"],
+        "max": ["total"],
+        "avg": ["total"],
+        "count": ["id"],
+        "distinctCount": ["status"]
+      },
+      "filters": { "status": "completed" }
+    }
+  },
+  "joinLeft": {
+    "creator": { "selection": "id,name,email" }
+  }
 }
 ```
 
+- **`filters`** — equality-based, flat key/value. Supports schema fields + `extraFilters`.
+- **`conditions`** — array of `{ field, method, params }`. Methods: `isEqual`, `isNotEqual`, `isGreater`, `isGreaterOrEqual`, `isLess`, `isLessOrEqual`, `isLike`, `isILike`, `isIn`, `isNotIn`, `isBetween`, `isNotBetween`, `isNull`, `isNotNull`.
+- **`joinMustExist`** — EXISTS-based filter: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Aliases must come from `allowedReadJoins` declarations with `unique: false`.
+- **`joinMultiple`** — fetches related child rows in a side query. Accepts `{ filters, conditions, selection }`. Same `unique: false` aliases.
+- **`joinGroup`** — aggregations on the related table. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY (a schema field name or a computed-field name declared on the join table — e.g. for date bucketing declare a computed using `db.dateTrunc('month', qiCol('orderDate'))`). Accepts `{ filters, conditions }`. Same `unique: false` aliases.
+- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-parti `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`.
+
+**Dot-notation in `orderBy` and `conditions`**:
+
+| Form | Source | Example |
+|------|--------|---------|
+| `<field>` | main schema | `orderBy=name ASC` |
+| `<alias>.<field>` | `joinLeft` aliases (`unique: true`) | `orderBy=creator.name ASC` |
+| `<alias>.<fn>.<field>` | `joinGroup` aliases declared in the same body | `orderBy=orders.sum.total DESC`, or `conditions: [{ field: 'orders.count.id', method: 'isGreaterOrEqual', params: [4] }]` |
+
 **Querystring** (optional): `orderBy`, `page`, `itemsPerPage`, `computeMin`, `computeMax`, `computeSum`, `computeAvg`
 
 **Response:**
@@ -258,12 +317,25 @@ Search with filters, pagination, ordering, joins, and aggregations.
 {
   "table": "customer",
   "main": [{ "id": 1, "name": "Mario", "email": "m@test.it" }],
-  "joins": { "order": [{ "id": 10, "customerId": 1, "total": 50 }] },
-  "pagination": { "total": 25, "pages": 3, "paginator": { "page": 1, "itemsPerPage": 20 } }
+  "joinLeft":     { "creator": [{ "id": 7, "name": "Alice", "email": "a@x.it" }] },
+  "joinMultiple": { "orders":  [{ "id": 10, "customerId": 1, "total": 50 }] },
+  "joinGroup": {
+    "orders": {
+      "sum": { "total": 300 },
+      "count": { "id": 2 },
+      "rows": [{ "by": "completed", "sum_total": 300, "count_id": 2 }]
+    }
+  },
+  "pagination": {
+    "total": 25,
+    "pages": 3,
+    "computed": { "min": { "id": 1 }, "max": { "id": 100 } },
+    "paginator": { "page": 1, "itemsPerPage": 20 }
+  }
 }
 ```
 
-`joins`, `joinGroups`, and `pagination` only appear when requested. A simple `{}` body returns `{ table, main }`.
+`joinLeft`, `joinMultiple`, `joinGroup`, and `pagination` appear only when requested. A simple `{}` body returns `{ table, main }`. `pagination.computed` appears only if `computeMin`/`computeMax`/`computeSum`/`computeAvg` are used.
 
 ### GET /rest/{table}/:id
 
@@ -277,12 +349,12 @@ Returns `{ main: { ... } }` or 404.
 {
   "main": { "name": "Mario", "email": "m@test.it" },
   "secondaries": {
-    "order": [{ "total": 50, "status": "pending" }]
+    "orders": [{ "total": 50, "status": "pending" }]
   }
 }
 ```
 
-`secondaries` is optional. FK fields are auto-filled from the inserted main record.
+`secondaries` keys are the **alias** declared in `allowedWriteJoins`. FK fields are auto-filled from the inserted main record.
 
 **Response (201):** `{ main: { ... }, secondaries: { ... } }`
 
@@ -293,8 +365,8 @@ Returns `{ main: { ... } }` or 404.
 ```json
 {
   "main": { "id": 1, "name": "Updated Name" },
-  "secondaries": { "order": [{ "total": 75 }] },
-  "deletions": { "order": [{ "id": 10 }] }
+  "secondaries": { "orders": [{ "total": 75 }] },
+  "deletions":   { "orders": [{ "id": 10 }] }
 }
 ```
 
@@ -312,6 +384,24 @@ Returns the deleted record or 404.
 
 **Body:** Array of objects with the PK field, e.g. `[{ "id": 1 }, { "id": 2 }]`. Executes as a single `DELETE WHERE pk IN (...)`.
 
+### Validation errors (400)
+
+Both schema-level (TypeBox/Ajv) and custom (`validate` / `validateBulk`) errors use the same response shape:
+
+```json
+{
+  "statusCode": 400,
+  "error": "Bad Request",
+  "message": "Validation failed",
+  "fields": [
+    { "path": "main.email", "code": "format", "message": "must match format \"email\"" },
+    { "path": "name", "code": "required", "message": "is required" }
+  ]
+}
+```
+
+Custom validators return tuples `[field, code]` or `[field, code, message]` — `message` defaults to `code` if omitted. `validateBulk` replaces per-item `validate` in bulk-upsert requests.
+
 ## Multi-Tenant
 
 Automatic row-level isolation on all CRUD operations. Configure once, no code in handlers.
@@ -405,9 +495,11 @@ await app.register(async (instance) => {
 
 ## Conventions
 
-- **camelCase in API, snake_case in DB** — the plugin converts automatically
-- **Joins are virtual** — they execute separate `SELECT ... WHERE fk IN (...)` queries, not SQL JOINs
-- **Hooks receive snake_case** — `beforeInsert` and `beforeUpdate` get snake_case records; `afterInsert` gets camelCase
+- **camelCase everywhere in the API** — requests, responses, `validate`, and all hooks (`beforeInsert`, `beforeUpdate`, `afterInsert`) use schema field names
+- **Conversion to DB column format is automatic** via `colMap` — supports both snake_case and camelCase DB columns (e.g. betterauth-style)
+- **Aliases identify joins** — declared in `buildRelation({ alias })`, used as keys in request/response/`secondaries`/dotted notation
+- **`joinMustExist` / `joinMultiple` / `joinGroup`** are 1:N (child→main) and use side queries / EXISTS / correlated subqueries — no row duplication
+- **`joinLeft`** is N:1 (parent→main) and adds a real `LEFT JOIN` on demand (only when filtering/ordering by parent)
 - **All response fields are Optional** — response schemas use `Type.Partial` since `RETURNING *` may return any subset
 
 ## Re-exports
@@ -417,23 +509,51 @@ The package re-exports commonly needed utilities so you don't need to install th
 ```typescript
 import {
   Type,                   // from @sinclair/typebox
+  type Static,            // from @sinclair/typebox
   ConditionBuilder,       // from node-condition-builder
   Expression,             // from node-condition-builder
-  QueryClient,            // raw SQL query helper
+
+  // Table configuration
   defineTable,
   exportTableInfo,
   buildRelation,
   buildUpsertRule,
   buildUpsertRules,
+
+  // DB layer
+  QueryClient,            // raw SQL query helper
+  createQueryClient,      // factory with dialect string
+  pgQueryable,            // pg pool adapter
+  mysqlQueryable,         // mysql2 pool adapter
+
+  // Programmatic high-level API
+  createSqlApi,           // standalone SqlApi (for scripts/tests)
+  setupSwagger,           // manual Swagger registration
+} from 'fastify-auto-sqlapi';
+
+import type {
+  ValidationError,        // [field, code] | [field, code, message]
+  ValidatorFn,
+  BulkValidatorFn,
+  JoinDefinition,
+  JoinRefFilter,
+  JoinFetchRequest,
+  JoinGroupRequest,
+  SearchCondition,
+  ConditionMethod,
 } from 'fastify-auto-sqlapi';
 ```
 
+After registering the plugin, `app.sqlApi` is decorated on the Fastify instance and exposes `search`, `get`, `insert`, `update`, `delete`, `bulkUpsert`, `bulkDelete` for custom routes — same code path as the auto-generated endpoints.
+
 ## Requirements
 
 - Node.js >= 18
-- PostgreSQL
-- Fastify >= 4
-- `@fastify/postgres` >= 5
+- Fastify >= 4 (peer dependency)
+- One of:
+  - **PostgreSQL** + `pg` + `@fastify/postgres`
+  - **MySQL** / **MariaDB** + `mysql2`
+- Optional: `@fastify/swagger` + `@fastify/swagger-ui` for Swagger UI
 
 ## License
 

package/dist/bin/generate-schema.js

@@ -5,28 +5,15 @@ import { loadConfig } from '../lib/cli/config.js';
 import { buildConnectionString, introspectTables } from '../lib/cli/pg-introspect.js';
 import { buildMysqlConnectionConfig, introspectMysqlTables } from '../lib/cli/mysql-introspect.js';
 import { buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
-import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, error } from './utils.js';
-loadEnvFile();
-function parseCliArgs() {
-    const args = process.argv.slice(2);
-    const result = {};
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--output' && i + 1 < args.length) {
-            result.output = args[++i];
-        }
-        else if (args[i] === '--tables' && i + 1 < args.length) {
-            result.tables = args[++i].split(',').map((t) => t.trim()).filter(Boolean);
-        }
-        else if (args[i] === '--dialect' && i + 1 < args.length) {
-            result.dialect = args[++i];
-        }
-    }
-    return result;
-}
-async function main() {
-    display('++++++ fastify-auto-sqlapi: generating schemas ++++++', CONSOLE_COLORS.yellow);
-    const cliArgs = parseCliArgs();
+import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, parseArgs, runCli } from './utils.js';
+await runCli('fastify-auto-sqlapi: generating schemas', async () => {
+    const cliArgs = parseArgs({
+        output: { type: 'value' },
+        tables: { type: 'list' },
+        dialect: { type: 'value' },
+    });
     const config = await loadConfig();
+    loadEnvFile(config.envFile);
     const dialect = (cliArgs.dialect || config.dialect || 'postgres');
     const schema = config.schema || (dialect === 'postgres' ? 'public' : config.schema || 'public');
     const outputDir = path.resolve(process.cwd(), cliArgs.output || config.outputDir);
@@ -51,7 +38,7 @@ async function main() {
     const tableMap = buildTableMap(rows);
     // Filter tables if --tables flag is provided
     const tableNames = cliArgs.tables;
-    if (tableNames) {
+    if (tableNames.length) {
         for (const schemaName of Object.keys(tableMap)) {
             if (!tableNames.includes(tableMap[schemaName].name)) {
                 delete tableMap[schemaName];
@@ -67,10 +54,10 @@ async function main() {
     let untouched = 0;
     const generatedFiles = new Set();
     for (const schemaName of Object.keys(tableMap)) {
-        const { name: tableName, fields } = tableMap[schemaName];
+        const { name: tableName, fields, colMap } = tableMap[schemaName];
         const filename = path.join(schemasDir, `${schemaName}.ts`);
         generatedFiles.add(`${schemaName}.ts`);
-        const content = generateSchemaFile(schemaName, tableName, fields);
+        const content = generateSchemaFile(schemaName, tableName, fields, colMap);
         let status = 'created';
         let color = CONSOLE_COLORS.green;
         if (fs.existsSync(filename)) {
@@ -94,7 +81,7 @@ async function main() {
         }
     }
     // Remove orphan Schema*.ts files (only when generating all tables)
-    if (!tableNames) {
+    if (!tableNames.length) {
         const existingFiles = fs.readdirSync(schemasDir);
         for (const file of existingFiles) {
             if (file.startsWith('Schema') && file.endsWith('.ts') && !generatedFiles.has(file)) {
@@ -115,8 +102,4 @@ async function main() {
     if (!somethingTouched) {
         display('All schemas are already up to date.', CONSOLE_COLORS.magenta);
     }
-}
-main().catch((e) => {
-    error(`Error: ${e.message}`);
-    process.exit(1);
 });

package/dist/bin/generate-tables.js

@@ -3,8 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { loadConfig } from '../lib/cli/config.js';
 import { parseSchemaFile, generateSingleTableFile, generateDbTablesIndex } from '../lib/cli/tables-codegen.js';
-import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, error } from './utils.js';
-loadEnvFile();
+import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, error, parseArgs, runCli } from './utils.js';
 function printHelp() {
     console.log('');
     display('Usage:', CONSOLE_COLORS.yellow);
@@ -23,39 +22,21 @@ function printHelp() {
     display('Table*.ts files are only created if they do not already exist.', CONSOLE_COLORS.magenta);
     display('dbTables.ts is always regenerated to include all schemas.', CONSOLE_COLORS.magenta);
 }
-function parseCliArgs() {
-    const args = process.argv.slice(2);
-    const result = { all: false, tables: [] };
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--output' && i + 1 < args.length) {
-            result.output = args[++i];
-        }
-        else if (args[i] === '--all') {
-            result.all = true;
-        }
-        else if (!args[i].startsWith('--')) {
-            // Split by comma to support both "a b" and "a,b" and "a, b"
-            for (const part of args[i].split(',')) {
-                const trimmed = part.trim();
-                if (trimmed)
-                    result.tables.push(trimmed);
-            }
-        }
-    }
-    return result;
-}
-async function main() {
-    const cliArgs = parseCliArgs();
+await runCli('fastify-auto-sqlapi: generating tables template', async () => {
+    const cliArgs = parseArgs({
+        output: { type: 'value' },
+        all: { type: 'flag' },
+        tables: { type: 'list' },
+    });
     if (!cliArgs.all && cliArgs.tables.length === 0) {
-        display('++++++ fastify-auto-sqlapi: generate tables template ++++++', CONSOLE_COLORS.yellow);
         printHelp();
         process.exit(1);
     }
-    display('++++++ fastify-auto-sqlapi: generating tables template ++++++', CONSOLE_COLORS.yellow);
     const config = await loadConfig();
+    loadEnvFile(config.envFile);
     const outputDir = path.resolve(process.cwd(), cliArgs.output || config.outputDir);
-    const schemasDir = outputDir;
-    const tablesDir = outputDir;
+    const schemasDir = path.join(outputDir, 'schemas');
+    const tablesDir = path.join(outputDir, 'tables');
     if (!fs.existsSync(schemasDir)) {
         error(`Schemas directory not found: ${schemasDir}`);
         display('Run sqlapi-generate-schema first.', CONSOLE_COLORS.magenta);
@@ -128,8 +109,4 @@ async function main() {
     }
     console.log('');
     display('Edit the generated Table*.ts files to customize your table configuration.', CONSOLE_COLORS.magenta);
-}
-main().catch((e) => {
-    error(`Error: ${e.message}`);
-    process.exit(1);
 });

package/dist/bin/utils.d.ts

@@ -2,7 +2,7 @@
  * Load .env file from cwd if it exists.
  * Does not override already-set environment variables.
  */
-export declare function loadEnvFile(): void;
+export declare function loadEnvFile(envFile?: string): void;
 export declare const CONSOLE_COLORS: {
     readonly black: 30;
     readonly gray: 90;
@@ -15,4 +15,32 @@ export declare const CONSOLE_COLORS: {
 export declare function displayAsTableRow(pref: string, value: string, distance: number, color?: number): void;
 export declare function display(text: string, color?: number): void;
 export declare function error(text: string): void;
+type ArgSpec = {
+    type: 'value';
+} | {
+    type: 'flag';
+} | {
+    type: 'list';
+};
+type ArgValue<S extends ArgSpec> = S['type'] extends 'flag' ? boolean : S['type'] extends 'list' ? string[] : string | undefined;
+/**
+ * Tiny declarative argv parser for the bundled CLIs.
+ * - `value`  → recognized as `--name X`, last value wins
+ * - `flag`   → recognized as `--name`, default false
+ * - `list`   → comma-separated `--name a,b,c`; can also accept positional comma-/space- separated tokens
+ *
+ * Positional tokens (non-`--`) are accumulated into `positional`. List specs auto-merge those tokens
+ * (split on ',') into the list as well, supporting both "a b" and "a,b" CLI shapes.
+ */
+export declare function parseArgs<S extends Record<string, ArgSpec>>(spec: S, argv?: string[]): {
+    [K in keyof S]: ArgValue<S[K]>;
+} & {
+    positional: string[];
+};
+/**
+ * CLI entry-point wrapper: prints a header, awaits `fn`, and turns thrown errors into a red message
+ * with a non-zero exit code (without aborting the process synchronously, so unfinished stdout flushes).
+ */
+export declare function runCli(name: string, fn: () => Promise<void>): Promise<void>;
+export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/bin/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/bin/utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAqBlC;AAED,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAU,GAChB,IAAI,CAQN;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,IAAI,CAE7D;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/bin/utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAqBlD;AAED,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAU,GAChB,IAAI,CAQN;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,IAAI,CAE7D;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExC;AAED,KAAK,OAAO,GACR;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,KAAK,QAAQ,CAAC,CAAC,SAAS,OAAO,IAC7B,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,GAAG,OAAO,GAClC,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,GACnC,MAAM,GAAG,SAAS,CAAC;AAErB;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,EACP,IAAI,WAAwB,GAC3B;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAyC/D;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF"}

package/dist/bin/utils.js

@@ -4,8 +4,8 @@ import { resolve } from 'node:path';
  * Load .env file from cwd if it exists.
  * Does not override already-set environment variables.
  */
-export function loadEnvFile() {
-    const envPath = resolve(process.cwd(), '.env');
+export function loadEnvFile(envFile) {
+    const envPath = resolve(process.cwd(), envFile || '.env');
     if (!existsSync(envPath))
         return;
     const content = readFileSync(envPath, 'utf-8');
@@ -52,3 +52,72 @@ export function display(text, color = 0) {
 export function error(text) {
     display(text, CONSOLE_COLORS.red);
 }
+/**
+ * Tiny declarative argv parser for the bundled CLIs.
+ * - `value`  → recognized as `--name X`, last value wins
+ * - `flag`   → recognized as `--name`, default false
+ * - `list`   → comma-separated `--name a,b,c`; can also accept positional comma-/space- separated tokens
+ *
+ * Positional tokens (non-`--`) are accumulated into `positional`. List specs auto-merge those tokens
+ * (split on ',') into the list as well, supporting both "a b" and "a,b" CLI shapes.
+ */
+export function parseArgs(spec, argv = process.argv.slice(2)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const out = { positional: [] };
+    for (const [name, def] of Object.entries(spec)) {
+        out[name] = def.type === 'flag' ? false : def.type === 'list' ? [] : undefined;
+    }
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            const name = token.slice(2);
+            const def = spec[name];
+            if (!def)
+                continue;
+            if (def.type === 'flag') {
+                out[name] = true;
+            }
+            else if (def.type === 'value' && i + 1 < argv.length) {
+                out[name] = argv[++i];
+            }
+            else if (def.type === 'list' && i + 1 < argv.length) {
+                const next = argv[++i];
+                for (const part of next.split(',')) {
+                    const t = part.trim();
+                    if (t)
+                        out[name].push(t);
+                }
+            }
+        }
+        else {
+            out.positional.push(token);
+            // Auto-distribute positional values into the (single) list spec, if any
+            for (const [n, def] of Object.entries(spec)) {
+                if (def.type === 'list') {
+                    for (const part of token.split(',')) {
+                        const t = part.trim();
+                        if (t)
+                            out[n].push(t);
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return out;
+}
+/**
+ * CLI entry-point wrapper: prints a header, awaits `fn`, and turns thrown errors into a red message
+ * with a non-zero exit code (without aborting the process synchronously, so unfinished stdout flushes).
+ */
+export async function runCli(name, fn) {
+    display(`++++++ ${name} ++++++`, CONSOLE_COLORS.yellow);
+    try {
+        await fn();
+    }
+    catch (e) {
+        error(`Error: ${e.message ?? String(e)}`);
+        process.exitCode = 1;
+    }
+}

package/dist/index.d.ts

@@ -30,5 +30,5 @@ export { BulkDeleteTableBody, BulkDeleteTableResponse } from './lib/schema/bulk-
 export { default as bulkDeleteRoutes } from './routes/auto/bulk-delete.routes.js';
 export { Type, type Static } from '@sinclair/typebox';
 export { ConditionBuilder, Expression } from 'node-condition-builder';
-export type { SqlApiConfig, ColumnInfo, TableMap, Queryable, SqlResult, DbRecord, DbRecordValue, SelectOptions, SchemaDefinition, JoinDefinition, ITable, DbTables, SqlApiPluginOptions, SwaggerOptions, SearchParams, SearchResult, Paginator, PaginationResult, TableFilterFn, ExtendedConditionFn, FilterRecord, AggregationRequest, JoinGroupRequest, GetParams, GetResult, DeleteParams, DeleteResult, InsertParams, InsertResult, BulkUpsertItem, BulkUpsertParams, BulkUpsertResult, BulkDeleteParams, BulkDeleteResult, ConditionMethod, SearchCondition, UpdateParams, UpdateResult, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantContext, ValidationError, ValidatorFn, BulkValidatorItem, BulkValidatorFn, } from './types.js';
+export type { SqlApiConfig, ColumnInfo, TableMap, Queryable, SqlResult, DbRecord, DbRecordValue, SelectOptions, SchemaDefinition, JoinDefinition, ITable, DbTables, SqlApiPluginOptions, SwaggerOptions, SearchParams, SearchResult, Paginator, PaginationResult, TableFilterFn, ExtendedConditionFn, FilterRecord, AggregationRequest, JoinGroupRequest, ComputedFieldFn, ComputedFieldContext, ComputedFieldExpr, GetParams, GetResult, DeleteParams, DeleteResult, InsertParams, InsertResult, BulkUpsertItem, BulkUpsertParams, BulkUpsertResult, BulkDeleteParams, BulkDeleteResult, ConditionMethod, SearchCondition, UpdateParams, UpdateResult, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantContext, ValidationError, ValidatorFn, BulkValidatorItem, BulkValidatorFn, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/cli/load-dependency.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Load an optional peer dependency by trying the consumer's CWD first
+ * (so it works when installed via `npm install`/`npm link`), then falling
+ * back to the plugin's own `node_modules` (so it works in the plugin's own tests).
+ * Throws a friendly error if neither succeeds.
+ */
+export declare function loadOptionalDependency<T = unknown>(modulePath: string, installHint: string): T;
+//# sourceMappingURL=load-dependency.d.ts.map

package/dist/lib/cli/load-dependency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-dependency.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/load-dependency.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,CAAC,CAW9F"}

package/dist/lib/cli/load-dependency.js

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module';
+/**
+ * Load an optional peer dependency by trying the consumer's CWD first
+ * (so it works when installed via `npm install`/`npm link`), then falling
+ * back to the plugin's own `node_modules` (so it works in the plugin's own tests).
+ * Throws a friendly error if neither succeeds.
+ */
+export function loadOptionalDependency(modulePath, installHint) {
+    try {
+        return createRequire(process.cwd() + '/noop.js')(modulePath);
+    }
+    catch {
+        /* fall through to local require */
+    }
+    try {
+        return createRequire(import.meta.url)(modulePath);
+    }
+    catch {
+        throw new Error(`${modulePath} is required. Install it with: ${installHint}`);
+    }
+}

package/dist/lib/cli/mysql-introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mysql-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/mysql-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,wBAAgB,0BAA0B,IAAI;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAmBA;AAkDD,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAClG,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}
+{"version":3,"file":"mysql-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/mysql-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,wBAAgB,0BAA0B,IAAI;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAmBA;AAkDD,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAClG,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CAyBvB"}