schematic-pg 0.1.4 → 0.1.6

package/README.md

@@ -201,21 +201,35 @@ npx schematic-pg init my-app
 cd my-app
 ```
 
-Edit `app.schema`, then generate code and start the API:
+Edit `app.schema`, then start the full dev loop:
 
 ```bash
-# Start PostgreSQL (PostGIS-enabled, matches .env defaults)
-docker compose up -d
+make dev
+# → starts PostgreSQL, generates code, bootstraps the DB, runs the dev server,
+#   and watches app.schema for changes (regenerate + bootstrap + restart)
+# → http://localhost:3000
+```
 
-# Generate schema.sql + generated/ (db client, routes, policies, Zod schemas)
-npx schematic-pg generate
+Or run each step individually:
 
-# Apply DDL to the database and snapshot schema state
-npx schematic-pg db:bootstrap
+```bash
+# Start PostgreSQL (PostGIS-enabled, matches .env defaults)
+docker compose up -d --wait
 
-# Regenerate client + API and start the server
+# Generate, bootstrap, start server, and watch app.schema (default)
 npx schematic-pg dev
 # → http://localhost:3000
+
+# One-shot dev server without schema watching:
+npx schematic-pg dev --no-watch
+```
+
+Manual split when you need finer control:
+
+```bash
+npx schematic-pg generate
+npx schematic-pg db:bootstrap
+npx schematic-pg dev --no-watch
 ```
 
 The `init` command creates everything you need to get running:
@@ -225,6 +239,7 @@ The `init` command creates everything you need to get running:
 | `app.schema` | Starter schema (one `User` model) — edit this |
 | `.env` | `DATABASE_URL`, JWT settings |
 | `docker-compose.yml` | Local PostGIS PostgreSQL on `:5432` |
+| `Makefile` | `make dev` — docker compose (with health wait) + `schematic-pg dev` |
 | `tsconfig.json` | TypeScript config for `generated/` and `src/routes/` |
 | `package.json` | `schematic-pg` + runtime deps (`hono`, `pg`, `zod`, …) |
 | `src/routes/health.ts` | Example custom route mounted at `/health` |
@@ -252,7 +267,7 @@ Generated code imports the runtime from the `schematic-pg` package (`schematic-p
 | `JWT_ROLE_CLAIM` | `role` | JWT claim mapped to `auth.role` |
 | `JWT_USER_ID_CLAIM` | `sub` | JWT claim mapped to `auth.user.id` |
 
-Set these in `.env` before running `db:bootstrap` or `dev`.
+Set these in `.env` before running `dev` or `db:bootstrap`.
 
 ---
 
@@ -280,12 +295,22 @@ Run `generate:client` before `generate:api` when using the split commands — ro
 ### Development server
 
 ```bash
-schematic-pg dev [schema]   # generate:client + generate:api, then start generated/app.ts
+schematic-pg dev [schema] [--no-watch]
 ```
 
+`dev` runs the full local loop:
+
+1. `generate` — writes `schema.sql` and `generated/*`
+2. `db:bootstrap` — waits for Postgres, applies DDL, snapshots schema state
+3. Starts `generated/app.ts`
+4. Watches `app.schema` (default) — on change, re-runs generate, bootstrap, and server restart
+
+Pass `--no-watch` for a one-shot run without file watching.
+
 Equivalent npm scripts in a project created by `init`:
 
 ```bash
+make dev           # docker compose up -d --wait + schematic-pg dev
 npm run dev        # schematic-pg dev
 npm run generate   # schematic-pg generate
 ```

package/dist/api-generator/utils/filter-operators.d.ts

@@ -11,4 +11,5 @@ export declare function getFilterFieldKind(field: Field, schema: Schema): Filter
 export declare function getFilterOperators(kind: FilterFieldKind): FilterOperator[];
 export declare function buildFilterFieldMeta(field: Field, schema: Schema): FilterFieldMeta;
 export declare function queryParamKey(fieldName: string, operator: FilterOperator): string;
+export declare function toQueryBooleanZodType(): string;
 export declare function toFilterZodType(type: TypeExpr, field: Field, schema: Schema, operator: FilterOperator, coerce?: boolean): string;

package/dist/api-generator/utils/filter-operators.js

@@ -54,6 +54,12 @@ export function queryParamKey(fieldName, operator) {
     }
     return `${fieldName}_${operator}`;
 }
+export function toQueryBooleanZodType() {
+    return `z.preprocess(
+    (value) => (typeof value === 'string' ? value.toLowerCase() : value),
+    z.union([z.boolean(), z.enum(['true', 'false'])]).transform((value) => value === true || value === 'true'),
+  )`;
+}
 export function toFilterZodType(type, field, schema, operator, coerce = false) {
     const prefix = coerce ? 'z.coerce.' : 'z.';
     const enumType = schema.enums.find((enumDef) => enumDef.name === type.name);
@@ -77,7 +83,7 @@ export function toFilterZodType(type, field, schema, operator, coerce = false) {
         case 'SMALLINT':
             return `${prefix}number().int()`;
         case 'BOOLEAN':
-            return `${prefix}boolean()`;
+            return toQueryBooleanZodType();
         case 'TIMESTAMP':
             return 'z.coerce.date()';
         case 'DECIMAL':

package/dist/api-generator/zod-schema-generator.js

@@ -86,8 +86,7 @@ export class ZodSchemaGenerator {
         const lines = [];
         for (const operator of meta.operators) {
             const key = queryParamKey(field.name, operator);
-            const useCoerce = operator !== 'equals' || field.type.name !== 'BOOLEAN';
-            const zodType = toFilterZodType(field.type, field, this.schema, operator, useCoerce);
+            const zodType = toFilterZodType(field.type, field, this.schema, operator, true);
             lines.push(`${key}: ${zodType}.optional(),`);
         }
         return lines;

package/dist/cli/db.js

@@ -5,6 +5,7 @@ import { applyPendingMigrations } from '../db/migrate.js';
 import { createMigration, getAppliedMigrationFilenames, listMigrationFiles } from '../db/migrations.js';
 import { snapshotExists } from '../db/schema-state.js';
 import { resolveSchemaPath } from './paths.js';
+import { waitForDatabase } from './wait-for-database.js';
 function parseDiffArgs(args) {
     let schemaPath = resolveSchemaPath();
     let name;
@@ -50,6 +51,7 @@ export async function runDbBootstrap(schemaPath) {
     const resolvedSchemaPath = resolveSchemaPath(schemaPath);
     const client = new DatabaseClient();
     try {
+        await waitForDatabase({ client });
         await bootstrapDatabase(resolvedSchemaPath, client);
         process.stdout.write(`Database bootstrapped from ${resolvedSchemaPath}\n`);
     }

package/dist/cli/dev.d.ts

@@ -1 +1 @@
-export declare function runDev(schemaPath?: string): Promise<void>;
+export declare function runDev(args?: string[]): Promise<void>;

package/dist/cli/dev.js

@@ -1,10 +1,150 @@
-import { execFileSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { watch } from 'node:fs';
 import path from 'node:path';
-import { generateApi, generateClient } from './generate.js';
-import { DEFAULT_OUTPUT_DIR } from './paths.js';
-export async function runDev(schemaPath) {
-    await generateClient(schemaPath);
-    await generateApi(schemaPath);
+import { runDbBootstrap } from './db.js';
+import { generateAll } from './generate.js';
+import { DEFAULT_OUTPUT_DIR, resolveSchemaPath } from './paths.js';
+const WATCH_DEBOUNCE_MS = 300;
+const SERVER_STOP_TIMEOUT_MS = 5000;
+function parseDevArgs(args) {
+    let schemaPath = resolveSchemaPath();
+    let watchSchema = true;
+    for (const arg of args) {
+        if (arg === '--no-watch') {
+            watchSchema = false;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            schemaPath = resolveSchemaPath(arg);
+        }
+    }
+    return { schemaPath, watchSchema };
+}
+function createDebouncer(fn, ms) {
+    let timer;
+    return () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void fn();
+        }, ms);
+    };
+}
+function startServer(appPath) {
+    return spawn(process.execPath, ['--import', 'tsx', appPath], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+    });
+}
+function stopServer(serverProcess) {
+    if (!serverProcess || serverProcess.exitCode !== null || serverProcess.killed) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        serverProcess.once('exit', () => resolve());
+        if (process.platform === 'win32') {
+            serverProcess.kill();
+        }
+        else {
+            serverProcess.kill('SIGTERM');
+        }
+        setTimeout(() => {
+            if (serverProcess.exitCode === null && !serverProcess.killed) {
+                serverProcess.kill('SIGKILL');
+            }
+        }, SERVER_STOP_TIMEOUT_MS);
+    });
+}
+function waitForServerExit(serverProcess) {
+    return new Promise((resolve) => {
+        serverProcess.once('exit', () => resolve());
+    });
+}
+export async function runDev(args = []) {
+    const { schemaPath, watchSchema } = parseDevArgs(args);
     const appPath = path.resolve(DEFAULT_OUTPUT_DIR, 'app.ts');
-    execFileSync(process.execPath, ['--import', 'tsx', appPath], { stdio: 'inherit', cwd: process.cwd() });
+    let serverProcess = null;
+    let syncInProgress = false;
+    let restarting = false;
+    let shuttingDown = false;
+    async function syncAndServe() {
+        if (syncInProgress) {
+            return;
+        }
+        syncInProgress = true;
+        try {
+            await generateAll(schemaPath);
+            await runDbBootstrap(schemaPath);
+            await stopServer(serverProcess);
+            serverProcess = startServer(appPath);
+            serverProcess.on('exit', (code, signal) => {
+                if (restarting || shuttingDown) {
+                    return;
+                }
+                if (!watchSchema) {
+                    if (code !== 0 && code !== null) {
+                        process.exitCode = code;
+                    }
+                    return;
+                }
+                if (code !== 0 && code !== null) {
+                    process.stderr.write(`Dev server exited with code ${code}\n`);
+                    process.exitCode = code;
+                    shuttingDown = true;
+                }
+                else if (signal) {
+                    process.stderr.write(`Dev server terminated by signal ${signal}\n`);
+                }
+            });
+        }
+        finally {
+            syncInProgress = false;
+        }
+    }
+    async function reload() {
+        if (shuttingDown || syncInProgress) {
+            return;
+        }
+        process.stderr.write('\nSchema changed — regenerating, bootstrapping, and restarting...\n');
+        restarting = true;
+        try {
+            await syncAndServe();
+        }
+        finally {
+            restarting = false;
+        }
+    }
+    const scheduleReload = createDebouncer(reload, WATCH_DEBOUNCE_MS);
+    async function shutdown() {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        await stopServer(serverProcess);
+    }
+    process.once('SIGINT', () => {
+        void shutdown().finally(() => {
+            process.exit(process.exitCode ?? 0);
+        });
+    });
+    process.once('SIGTERM', () => {
+        void shutdown().finally(() => {
+            process.exit(process.exitCode ?? 0);
+        });
+    });
+    await syncAndServe();
+    if (!watchSchema) {
+        if (serverProcess) {
+            await waitForServerExit(serverProcess);
+        }
+        return;
+    }
+    watch(schemaPath, scheduleReload);
+    await new Promise((resolve) => {
+        const interval = setInterval(() => {
+            if (shuttingDown) {
+                clearInterval(interval);
+                resolve();
+            }
+        }, 100);
+    });
 }

package/dist/cli/init.js

@@ -3,12 +3,13 @@ import { PACKAGE_NAME } from '../constants.js';
 import { existsSync } from 'node:fs';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { APP_SCHEMA_TEMPLATE, createPackageJsonTemplate, DOCKER_COMPOSE_TEMPLATE, ENV_TEMPLATE, GITIGNORE_TEMPLATE, HEALTH_ROUTE_TEMPLATE, TSCONFIG_TEMPLATE, } from './templates.js';
+import { APP_SCHEMA_TEMPLATE, createPackageJsonTemplate, DOCKER_COMPOSE_TEMPLATE, ENV_TEMPLATE, GITIGNORE_TEMPLATE, HEALTH_ROUTE_TEMPLATE, MAKEFILE_TEMPLATE, TSCONFIG_TEMPLATE, } from './templates.js';
 const INIT_FILES = [
     { relativePath: 'app.schema', content: APP_SCHEMA_TEMPLATE },
     { relativePath: '.env', content: ENV_TEMPLATE },
     { relativePath: '.gitignore', content: GITIGNORE_TEMPLATE },
     { relativePath: 'docker-compose.yml', content: DOCKER_COMPOSE_TEMPLATE },
+    { relativePath: 'Makefile', content: MAKEFILE_TEMPLATE },
     { relativePath: 'tsconfig.json', content: TSCONFIG_TEMPLATE },
     { relativePath: 'src/routes/health.ts', content: HEALTH_ROUTE_TEMPLATE },
 ];
@@ -101,8 +102,14 @@ export async function runInit(args) {
     if (skipInstall) {
         console.log('  npm install');
     }
-    console.log('  docker compose up -d');
+    console.log('  make dev');
+    console.log('');
+    console.log('  # or run individually:');
+    console.log('  docker compose up -d --wait');
+    console.log(`  npx ${PACKAGE_NAME} dev   # generate + bootstrap + server + schema watch`);
+    console.log('');
+    console.log('  # split steps (dev already includes generate, bootstrap, and watch):');
     console.log(`  npx ${PACKAGE_NAME} generate`);
     console.log(`  npx ${PACKAGE_NAME} db:bootstrap`);
-    console.log(`  npx ${PACKAGE_NAME} dev`);
+    console.log(`  npx ${PACKAGE_NAME} dev --no-watch`);
 }

package/dist/cli/templates.d.ts

@@ -1,7 +1,8 @@
-export declare const APP_SCHEMA_TEMPLATE = "models {\n  model User {\n    id:        UUID        @id @default(gen_random_uuid())\n    email:     VARCHAR(255) @unique\n    name:      VARCHAR(150)\n    createdAt: TIMESTAMP   @default(now())\n  }\n}\n";
+export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n\n}\n\nmodels {\n  model User {\n    id:        UUID        @id @default(gen_random_uuid())\n    email:     VARCHAR(255) @unique\n    name:      VARCHAR(150)\n    createdAt: TIMESTAMP   @default(now())\n  }\n}\n";
 export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\n";
 export declare const GITIGNORE_TEMPLATE = "node_modules/\ndist/\n.env\ndocker_data/\n.DS_Store\n*.log\nnpm-debug.log*\n";
 export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgis/postgis:16-3.4\n    container_name: schematic-pg-postgres\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"outDir\": \"dist\",\n    \"rootDir\": \".\"\n  },\n  \"include\": [\"generated/**/*\", \"src/**/*\"]\n}\n";
+export declare const MAKEFILE_TEMPLATE = ".PHONY: dev\n\ndev:\n\tdocker compose up -d --wait\n\tnpx schematic-pg dev\n";
 export declare const HEALTH_ROUTE_TEMPLATE = "import { Hono } from 'hono';\nimport type { AppEnv } from 'schematic-pg/api/types';\n\nconst router = new Hono<AppEnv>();\nrouter.get('/', (c) => c.json({ ok: true }));\nexport default router;\n";
 export declare function createPackageJsonTemplate(projectName: string): string;

package/dist/cli/templates.js

@@ -1,5 +1,13 @@
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../constants.js';
-export const APP_SCHEMA_TEMPLATE = `models {
+export const APP_SCHEMA_TEMPLATE = `extensions {
+
+}
+
+enums {
+
+}
+
+models {
   model User {
     id:        UUID        @id @default(gen_random_uuid())
     email:     VARCHAR(255) @unique
@@ -54,6 +62,12 @@ export const TSCONFIG_TEMPLATE = `{
   "include": ["generated/**/*", "src/**/*"]
 }
 `;
+export const MAKEFILE_TEMPLATE = `.PHONY: dev
+
+dev:
+\tdocker compose up -d --wait
+\tnpx ${PACKAGE_NAME} dev
+`;
 export const HEALTH_ROUTE_TEMPLATE = `import { Hono } from 'hono';
 import type { AppEnv } from '${PACKAGE_NAME}/api/types';
 

package/dist/cli/wait-for-database.d.ts

@@ -0,0 +1,9 @@
+import { DatabaseClient } from '../db/client.js';
+export type WaitForDatabaseOptions = {
+    maxAttempts?: number;
+    intervalMs?: number;
+    client?: Pick<DatabaseClient, 'query'>;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare function pingDatabase(client: Pick<DatabaseClient, 'query'>): Promise<void>;
+export declare function waitForDatabase(options?: WaitForDatabaseOptions): Promise<void>;

package/dist/cli/wait-for-database.js

@@ -0,0 +1,39 @@
+import { DatabaseClient } from '../db/client.js';
+export async function pingDatabase(client) {
+    const result = await client.query('SELECT 1 AS ok');
+    const ok = result.rows[0]?.ok;
+    if (ok !== 1) {
+        throw new Error(`Unexpected ping result: ${String(ok)}`);
+    }
+}
+export async function waitForDatabase(options = {}) {
+    const maxAttempts = options.maxAttempts ?? 30;
+    const intervalMs = options.intervalMs ?? 1000;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const ownClient = options.client ? null : new DatabaseClient();
+    const client = options.client ?? ownClient;
+    try {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                await pingDatabase(client);
+                if (attempt > 1) {
+                    process.stderr.write(`Database ready (attempt ${attempt}/${maxAttempts})\n`);
+                }
+                return;
+            }
+            catch (error) {
+                if (attempt === maxAttempts) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Database not ready after ${maxAttempts} attempts (${intervalMs}ms interval): ${message}`);
+                }
+                process.stderr.write(`Waiting for database (${attempt}/${maxAttempts})...\n`);
+                await sleep(intervalMs);
+            }
+        }
+    }
+    finally {
+        if (ownClient) {
+            await ownClient.close();
+        }
+    }
+}

package/dist/cli.js

@@ -12,7 +12,7 @@ Commands:
   generate:sql [schema]      Generate SQL DDL to stdout
   generate:client [schema]   Generate db client files
   generate:api [schema]      Generate API files
-  dev [schema]               Regenerate client + API and start server
+  dev [schema] [--no-watch]  Generate, bootstrap DB, start server, watch schema
   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)
@@ -50,7 +50,7 @@ async function main() {
                 await generateApi(schemaPath);
                 break;
             case 'dev':
-                await runDev(schemaPath);
+                await runDev(args);
                 break;
             case 'db:ping':
                 await runDbPing();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",