schematic-pg 0.1.7 → 0.1.10

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { runDbBootstrap, runDbDiff, runDbMigrate, runDbPing } from './cli/db.js';
 import { runDev } from './cli/dev.js';
+import { runStart } from './cli/start.js';
 import { generateAll, generateApi, generateClient, generateSql } from './cli/generate.js';
+import { runHooksAdd } from './cli/hooks.js';
 import { runInit } from './cli/init.js';
 import { PACKAGE_NAME } from './constants.js';
 const USAGE = `Usage: ${PACKAGE_NAME} <command> [options]
@@ -12,7 +14,9 @@ Commands:
   generate:sql [schema]      Generate SQL DDL to stdout
   generate:client [schema]   Generate db client files
   generate:api [schema]      Generate API files
+  hooks:add [schema] [--model ModelName]  Scaffold lifecycle hooks for a model
   dev [schema] [--no-watch]  Generate, bootstrap DB, start server, watch schema
+  start [schema] [--no-migrate]  Run production server (migrate DB, no generate/watch)
   db:ping                    Test database connection
   db:bootstrap [schema]      Apply DDL and snapshot schema state
   db:diff [schema]           Show schema diff (--name <name> to write migration)
@@ -49,9 +53,15 @@ async function main() {
             case 'generate:api':
                 await generateApi(schemaPath);
                 break;
+            case 'hooks:add':
+                await runHooksAdd(args);
+                break;
             case 'dev':
                 await runDev(args);
                 break;
+            case 'start':
+                await runStart(args);
+                break;
             case 'db:ping':
                 await runDbPing();
                 break;

package/dist/db/db-client-generator.js

@@ -31,10 +31,13 @@ export class DbClientGenerator {
             "import type { Pool } from 'pg';",
             `import { createModelClient } from '${PACKAGE_NAME}/db/model-client';`,
             `import { hydrateModelMeta } from '${PACKAGE_NAME}/db/model-meta';`,
+            `import type { Queryable } from '${PACKAGE_NAME}/db/queryable';`,
+            `import { createRawClient } from '${PACKAGE_NAME}/db/raw';`,
+            `import { runInTransaction } from '${PACKAGE_NAME}/db/transaction';`,
             `import type {\n  ${imports},\n} from './db-types.js';`,
             `import {\n  ${this.schema.models.map((model) => `${getClientExportName(model.name)}ModelMeta`).join(',\n  ')},\n} from './db-model-meta.js';`,
             '',
-            'export function createDbClient(pool: Pool) {',
+            'function buildModels(executor: Queryable) {',
             ...metaHydrations,
             `  const modelRegistry = new Map([`,
             ...registryEntries.map((entry) => `    ${entry},`),
@@ -42,6 +45,21 @@ export class DbClientGenerator {
             '',
             '  return {',
             clientEntries.map((entry) => `    ${entry},`).join('\n'),
+            '    ...createRawClient(executor),',
+            '  };',
+            '}',
+            '',
+            '/** All model clients scoped to a single transaction. Nested `$transaction` is unsupported. */',
+            'export type TxClient = ReturnType<typeof buildModels>;',
+            '',
+            'export function createDbClient(pool: Pool) {',
+            '  async function $transaction<T>(fn: (tx: TxClient) => Promise<T>): Promise<T> {',
+            '    return runInTransaction(pool, (client) => fn(buildModels(client)));',
+            '  }',
+            '',
+            '  return {',
+            '    ...buildModels(pool),',
+            '    $transaction,',
             '  };',
             '}',
             '',
@@ -65,7 +83,7 @@ export class DbClientGenerator {
     }
     generateClientEntry(modelName) {
         const clientKey = getClientExportName(modelName);
-        return `${clientKey}: createModelClient<${modelName}, ${modelName}CreateInput, ${modelName}UpdateInput, ${modelName}WhereInput, ${modelName}OrderByInput>(${clientKey}Meta, pool, modelRegistry)`;
+        return `${clientKey}: createModelClient<${modelName}, ${modelName}CreateInput, ${modelName}UpdateInput, ${modelName}WhereInput, ${modelName}OrderByInput>(${clientKey}Meta, executor, modelRegistry)`;
     }
 }
 export function generateDbClientFiles(schema) {

package/dist/db/include/executor.d.ts

@@ -1,3 +1,3 @@
-import type { Pool } from 'pg';
+import type { Queryable } from '../queryable.js';
 import type { LoadNode } from './planner.js';
-export declare function loadIncludes(parentRows: Record<string, unknown>[], plan: LoadNode, pool: Pool): Promise<void>;
+export declare function loadIncludes(parentRows: Record<string, unknown>[], plan: LoadNode, executor: Queryable): Promise<void>;

package/dist/db/include/executor.js

@@ -2,7 +2,7 @@ import { mapPgError } from '../errors.js';
 import { mapRows } from '../row-mapper.js';
 import { WhereTranslator } from '../where-translator.js';
 import { dedupeKeys, extractParentKeys, stitch } from './hydrator.js';
-export async function loadIncludes(parentRows, plan, pool) {
+export async function loadIncludes(parentRows, plan, executor) {
     for (const childPlan of plan.children) {
         const relation = childPlan.relation;
         if (!relation) {
@@ -13,8 +13,8 @@ export async function loadIncludes(parentRows, plan, pool) {
             assignEmptyRelation(parentRows, relation);
             continue;
         }
-        const childRows = await fetchRelationRows(childPlan, parentKeys, pool);
-        await loadIncludes(childRows, childPlan, pool);
+        const childRows = await fetchRelationRows(childPlan, parentKeys, executor);
+        await loadIncludes(childRows, childPlan, executor);
         stitch(parentRows, childRows, relation);
     }
 }
@@ -23,13 +23,13 @@ function assignEmptyRelation(parentRows, relation) {
         parent[relation.name] = relation.unique ? null : [];
     }
 }
-async function fetchRelationRows(node, parentKeys, pool) {
+async function fetchRelationRows(node, parentKeys, executor) {
     const relation = node.relation;
     if (!relation) {
         return [];
     }
     const query = buildRelationSelect(node, parentKeys);
-    const rows = await executeQuery(pool, query.sql, query.params, node.model);
+    const rows = await executeQuery(executor, query.sql, query.params, node.model);
     return mapRows(rows, node.model);
 }
 function buildRelationSelect(node, parentKeys) {
@@ -79,9 +79,9 @@ function buildOrderByClause(plan) {
     }
     return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : '';
 }
-async function executeQuery(pool, sql, params, model) {
+async function executeQuery(executor, sql, params, model) {
     try {
-        const result = await pool.query(sql, params);
+        const result = await executor.query(sql, params);
         return result.rows;
     }
     catch (error) {

package/dist/db/include/json-agg.d.ts

@@ -1,5 +1,5 @@
-import type { Pool } from 'pg';
 import type { ModelMeta } from '../model-meta.js';
 import type { FindArgs } from '../query-builder.js';
+import type { Queryable } from '../queryable.js';
 import type { LoadNode } from './planner.js';
-export declare function fetchRootWithJsonAgg<T extends Record<string, unknown>>(model: ModelMeta, plan: LoadNode, args: FindArgs, pool: Pool): Promise<T[]>;
+export declare function fetchRootWithJsonAgg<T extends Record<string, unknown>>(model: ModelMeta, plan: LoadNode, args: FindArgs, executor: Queryable): Promise<T[]>;

package/dist/db/include/json-agg.js

@@ -2,9 +2,9 @@ import { mapPgError } from '../errors.js';
 import { QueryBuilder } from '../query-builder.js';
 import { mapRow } from '../row-mapper.js';
 const ROOT_ALIAS = 'root';
-export async function fetchRootWithJsonAgg(model, plan, args, pool) {
+export async function fetchRootWithJsonAgg(model, plan, args, executor) {
     const query = buildJsonAggRootQuery(model, plan, args);
-    const rows = await executeQuery(pool, query.sql, query.params, model);
+    const rows = await executeQuery(executor, query.sql, query.params, model);
     return rows.map((row) => hydrateJsonAggRow(row, model, plan));
 }
 function buildJsonAggRootQuery(model, plan, args) {
@@ -90,9 +90,9 @@ function hydrateJsonObject(value, plan) {
     }
     return mapped;
 }
-async function executeQuery(pool, sql, params, model) {
+async function executeQuery(executor, sql, params, model) {
     try {
-        const result = await pool.query(sql, params);
+        const result = await executor.query(sql, params);
         return result.rows;
     }
     catch (error) {

package/dist/db/include/load.d.ts

@@ -1,8 +1,8 @@
-import type { Pool } from 'pg';
 import type { ModelMeta } from '../model-meta.js';
 import type { FindArgs } from '../query-builder.js';
+import type { Queryable } from '../queryable.js';
 import type { IncludeInput, IncludeOptions } from './types.js';
-export declare function fetchWithIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, pool: Pool, rootArgs: FindArgs & {
+export declare function fetchWithIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, executor: Queryable, rootArgs: FindArgs & {
     include?: IncludeInput;
 }, options?: IncludeOptions): Promise<T[]>;
-export declare function attachIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, pool: Pool, rootRows: T[], include: IncludeInput, rootArgs: FindArgs, options?: IncludeOptions): Promise<T[]>;
+export declare function attachIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, executor: Queryable, rootRows: T[], include: IncludeInput, rootArgs: FindArgs, options?: IncludeOptions): Promise<T[]>;

package/dist/db/include/load.js

@@ -4,7 +4,7 @@ import { mapRows } from '../row-mapper.js';
 import { loadIncludes } from './executor.js';
 import { fetchRootWithJsonAgg } from './json-agg.js';
 import { buildLoadPlan } from './planner.js';
-export async function fetchWithIncludes(model, registry, pool, rootArgs, options = {}) {
+export async function fetchWithIncludes(model, registry, executor, rootArgs, options = {}) {
     if (!rootArgs.include) {
         throw new Error('fetchWithIncludes requires include');
     }
@@ -14,14 +14,14 @@ export async function fetchWithIncludes(model, registry, pool, rootArgs, options
     plan.take = rootArgs.take;
     plan.skip = rootArgs.skip;
     if (plan.strategy === 'join') {
-        return fetchRootWithJsonAgg(model, plan, rootArgs, pool);
+        return fetchRootWithJsonAgg(model, plan, rootArgs, executor);
     }
-    const rows = await executeRootSelect(model, pool, rootArgs);
+    const rows = await executeRootSelect(model, executor, rootArgs);
     const mapped = mapRows(rows, model);
-    await loadIncludes(mapped, plan, pool);
+    await loadIncludes(mapped, plan, executor);
     return mapped;
 }
-export async function attachIncludes(model, registry, pool, rootRows, include, rootArgs, options = {}) {
+export async function attachIncludes(model, registry, executor, rootRows, include, rootArgs, options = {}) {
     if (rootRows.length === 0) {
         return rootRows;
     }
@@ -30,14 +30,14 @@ export async function attachIncludes(model, registry, pool, rootRows, include, r
     plan.orderBy = rootArgs.orderBy;
     plan.take = rootArgs.take;
     plan.skip = rootArgs.skip;
-    await loadIncludes(rootRows, plan, pool);
+    await loadIncludes(rootRows, plan, executor);
     return rootRows;
 }
-async function executeRootSelect(model, pool, args) {
+async function executeRootSelect(model, executor, args) {
     const builder = new QueryBuilder(model);
     const query = builder.select(args);
     try {
-        const result = await pool.query(query.sql, query.params);
+        const result = await executor.query(query.sql, query.params);
         return result.rows;
     }
     catch (error) {

package/dist/db/index.d.ts

@@ -4,6 +4,10 @@ export { getDatabaseUrl } from './config.js';
 export { QueryBuilder } from './query-builder.js';
 export { WhereTranslator } from './where-translator.js';
 export { createModelClient } from './model-client.js';
+export type { Queryable } from './queryable.js';
+export { createRawClient } from './raw.js';
+export type { RawClient } from './raw.js';
+export { runInTransaction } from './transaction.js';
 export { TypeGenerator, generateDbTypes } from './type-generator.js';
 export { DbClientGenerator, generateDbClientFiles } from './db-client-generator.js';
 export { buildModelMeta, buildModelMetaSnapshot, hydrateModelMeta } from './model-meta.js';

package/dist/db/index.js

@@ -4,6 +4,8 @@ export { getDatabaseUrl } from './config.js';
 export { QueryBuilder } from './query-builder.js';
 export { WhereTranslator } from './where-translator.js';
 export { createModelClient } from './model-client.js';
+export { createRawClient } from './raw.js';
+export { runInTransaction } from './transaction.js';
 export { TypeGenerator, generateDbTypes } from './type-generator.js';
 export { DbClientGenerator, generateDbClientFiles } from './db-client-generator.js';
 export { buildModelMeta, buildModelMetaSnapshot, hydrateModelMeta } from './model-meta.js';

package/dist/db/model-client.d.ts

@@ -1,6 +1,6 @@
-import type { Pool } from 'pg';
 import type { IncludeInput, IncludeOptions } from './include/types.js';
 import type { ModelMeta } from './model-meta.js';
+import type { Queryable } from './queryable.js';
 export type ModelRegistry = Map<string, ModelMeta>;
 export interface SelectArgs<TWhere, TOrderBy> {
     where?: TWhere;
@@ -35,4 +35,4 @@ export interface ModelClient<T, TCreate, TUpdate, TWhere, TOrderBy> {
         count: number;
     }>;
 }
-export declare function createModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>(model: ModelMeta, pool: Pool, registry?: ModelRegistry): ModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>;
+export declare function createModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>(model: ModelMeta, executor: Queryable, registry?: ModelRegistry): ModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>;

package/dist/db/model-client.js

@@ -2,11 +2,11 @@ import { mapPgError } from './errors.js';
 import { fetchWithIncludes } from './include/load.js';
 import { QueryBuilder } from './query-builder.js';
 import { mapRow, mapRows } from './row-mapper.js';
-export function createModelClient(model, pool, registry) {
+export function createModelClient(model, executor, registry) {
     const builder = new QueryBuilder(model);
     async function execute(sql, params) {
         try {
-            const result = await pool.query(sql, params);
+            const result = await executor.query(sql, params);
             return result.rows;
         }
         catch (error) {
@@ -16,7 +16,7 @@ export function createModelClient(model, pool, registry) {
     async function selectRows(args = {}) {
         const findArgs = toFindArgs(args);
         if (args.include && registry) {
-            return fetchWithIncludes(model, registry, pool, {
+            return fetchWithIncludes(model, registry, executor, {
                 ...findArgs,
                 include: args.include,
             }, {

package/dist/db/queryable.d.ts

@@ -0,0 +1,5 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+/** Minimal executor satisfied by both pg `Pool` and `PoolClient`. */
+export interface Queryable {
+    query<T extends QueryResultRow>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+}

package/dist/db/queryable.js

@@ -0,0 +1 @@
+export {};

package/dist/db/raw.d.ts

@@ -0,0 +1,22 @@
+import type { QueryResultRow } from 'pg';
+import type { Queryable } from './queryable.js';
+export interface RawClient {
+    /**
+     * Runs an arbitrary SQL query and returns the raw result rows.
+     *
+     * Rows are returned EXACTLY as `pg` produces them: `snake_case` column names
+     * and driver type coercion, with no `camelCase` mapping. Values MUST be passed
+     * through the positional `params` array (`$1`, `$2`, …) — never interpolate
+     * user input into the `sql` string.
+     */
+    $queryRaw<T extends QueryResultRow = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Runs an arbitrary SQL statement and returns the number of affected rows.
+     *
+     * Values MUST be passed through the positional `params` array (`$1`, `$2`, …)
+     * — never interpolate user input into the `sql` string.
+     */
+    $executeRaw(sql: string, params?: unknown[]): Promise<number>;
+}
+/** Builds the parameterized raw-query escape hatch bound to a single executor. */
+export declare function createRawClient(executor: Queryable): RawClient;

package/dist/db/raw.js

@@ -0,0 +1,35 @@
+import { mapPgError } from './errors.js';
+/**
+ * Label used when surfacing raw-query errors. A raw query has no single owning
+ * model, so error mapping runs without a `column -> field` translation map.
+ */
+const RAW_QUERY_LABEL = '$queryRaw';
+const EMPTY_COLUMN_TO_FIELD = new Map();
+const NO_PARAMS = [];
+/** Maps a driver error to the project's typed `DatabaseError` subclasses. */
+function wrapRawError(error) {
+    return mapPgError(error, RAW_QUERY_LABEL, EMPTY_COLUMN_TO_FIELD);
+}
+/** Builds the parameterized raw-query escape hatch bound to a single executor. */
+export function createRawClient(executor) {
+    return {
+        async $queryRaw(sql, params = NO_PARAMS) {
+            try {
+                const result = await executor.query(sql, params);
+                return result.rows;
+            }
+            catch (error) {
+                throw wrapRawError(error);
+            }
+        },
+        async $executeRaw(sql, params = NO_PARAMS) {
+            try {
+                const result = await executor.query(sql, params);
+                return result.rowCount ?? 0;
+            }
+            catch (error) {
+                throw wrapRawError(error);
+            }
+        },
+    };
+}

package/dist/db/transaction.d.ts

@@ -0,0 +1,2 @@
+import type { Pool, PoolClient } from 'pg';
+export declare function runInTransaction<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;

package/dist/db/transaction.js

@@ -0,0 +1,24 @@
+const BEGIN = 'BEGIN';
+const COMMIT = 'COMMIT';
+const ROLLBACK = 'ROLLBACK';
+export async function runInTransaction(pool, fn) {
+    const client = await pool.connect();
+    try {
+        await client.query(BEGIN);
+        const result = await fn(client);
+        await client.query(COMMIT);
+        return result;
+    }
+    catch (error) {
+        try {
+            await client.query(ROLLBACK);
+        }
+        catch {
+            // ignore rollback failure; surface the original error
+        }
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}

package/dist/routes/auth.d.ts

@@ -0,0 +1,3 @@
+/** Demo User requires balance; register bypasses @policy and writes via db.user.create. */
+declare const _default: import("hono").Hono<import("../api/types.js").AppEnv, import("hono/types").BlankSchema, "/">;
+export default _default;

package/dist/routes/auth.js

@@ -0,0 +1,5 @@
+import { createAuthRouter } from 'schematic-pg/api/auth/routes';
+/** Demo User requires balance; register bypasses @policy and writes via db.user.create. */
+export default createAuthRouter({
+    defaultCreateFields: { balance: 0 },
+});

package/dist/types/generated-db.stub.d.ts

@@ -1,2 +1,6 @@
-export type DbClient = Record<string, unknown>;
+import type { QueryResultRow } from 'pg';
+export interface DbClient extends Record<string, unknown> {
+    $queryRaw<T extends QueryResultRow = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    $executeRaw(sql: string, params?: unknown[]): Promise<number>;
+}
 export declare function createDbClient(_pool: unknown): DbClient;

package/dist/types/generated-db.stub.js

@@ -1,3 +1,10 @@
 export function createDbClient(_pool) {
-    return {};
+    return {
+        async $queryRaw() {
+            return [];
+        },
+        async $executeRaw() {
+            return 0;
+        },
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tawsbob/postgrest.js.git"
+    "url": "git+https://github.com/tawsbob/schematic-pg.git"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,6 +34,10 @@
       "types": "./dist/schema-dsl/index.d.ts",
       "import": "./dist/schema-dsl/index.js"
     },
+    "./api/hooks": {
+      "types": "./dist/api/hooks/index.d.ts",
+      "import": "./dist/api/hooks/index.js"
+    },
     "./api/*": {
       "types": "./dist/api/*.d.ts",
       "import": "./dist/api/*.js"
@@ -44,13 +48,14 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && mkdir -p dist/cli/templates && cp src/cli/templates/agents.md dist/cli/templates/",
     "parse": "tsx src/schema-dsl/cli.ts",
     "tokenize": "tsx src/schema-dsl/cli.ts --tokens",
     "generate": "tsx src/cli.ts generate",
     "generate:client": "tsx src/cli.ts generate:client",
     "generate:api": "tsx src/cli.ts generate:api",
     "dev:api": "tsx src/cli.ts dev",
+    "start": "tsx src/cli.ts start",
     "setup:env": "test -f .env || cp .env.example .env",
     "db:ping": "tsx src/cli.ts db:ping",
     "db:bootstrap": "tsx src/cli.ts db:bootstrap",
@@ -60,7 +65,7 @@
     "build:lsp": "npm run build --workspace=@schematic-pg/schema-dsl-language-server",
     "build:extension": "npm run vscode:prepublish --workspace=schematic-pg-schema-dsl-vscode && npm run package --workspace=schematic-pg-schema-dsl-vscode",
     "test": "node --import tsx --test $(find src editors/language-server -path '*/__tests__/*.test.ts' ! -name '*.integration.test.ts')",
-    "test:integration": "npm run setup:env && docker compose up -d --wait && npm run generate:client && npm run generate:api && JWT_SECRET=integration-test-secret node --import tsx --test --test-concurrency=1 'src/**/__tests__/**/*.integration.test.ts'",
+    "test:integration": "npm run setup:env && docker compose up -d --wait && npm run generate:client && npm run generate:api && JWT_SECRET=integration-test-secret AUTH_PEPPER=integration-test-pepper node --import tsx --test --test-concurrency=1 'src/**/__tests__/**/*.integration.test.ts'",
     "docker:up": "docker compose up -d",
     "docker:down": "docker compose down",
     "docker:logs": "docker compose logs -f postgres",
@@ -69,6 +74,8 @@
   "dependencies": {
     "@hono/node-server": "^2.0.6",
     "@hono/zod-validator": "^0.8.0",
+    "@inquirer/prompts": "^8.5.2",
+    "argon2": "^0.44.0",
     "hono": "^4.12.27",
     "pg": "^8.22.0",
     "tsx": "^4.19.4",