@an5/orm 1.3.2 → 1.3.3

package/README.md

@@ -69,38 +69,58 @@ DATABASE_URL=sqlserver://localhost:1433;database=mydb;user=sa;password=Secret123
 
 ### CLI Commands
 
+You can run AN5 commands directly using `npx @an5/orm` (or `npx an5`):
+
 ```bash
 # Generate client code from .an5 schemas
-npm run generate
+npx @an5/orm generate
+# or: npx an5 generate
 
 # Push schema directly to database
-npm run db:push
+npx @an5/orm db:push
 
 # Pull database schema into .an5 files
-npm run db:pull
+npx @an5/orm db:pull
 
 # Check schema diff
-npm run db:migrate diff
+npx @an5/orm db:migrate diff
 
 # Generate new migration script
-npm run db:migrate:generate
+npx @an5/orm db:migrate generate
 
 # Apply pending migrations
-npm run db:migrate:apply
+npx @an5/orm db:migrate apply
 
 # Rollback last migration
-npm run db:migrate:rollback
+npx @an5/orm db:migrate rollback
 
 # View migration status
-npm run db:migrate:status
+npx @an5/orm db:migrate status
 
 # Run database seed script
-npm run db:seed
+npx @an5/orm db:seed
 
-# Clean up database tables
-npm run db:cleanup
+# Clean up extra tables and views
+npx @an5/orm db:cleanup
 ```
 
+You can also add these commands to your project's `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "generate": "an5 generate",
+    "db:push": "an5 db:push",
+    "db:pull": "an5 db:pull",
+    "db:migrate": "an5 db:migrate",
+    "db:seed": "an5 db:seed",
+    "db:cleanup": "an5 db:cleanup"
+  }
+}
+```
+
+Then run them with `npm run generate`, `npm run db:push`, etc.
+
 ## Runtime Database Usage (via `@an5/adapters`)
 
 To connect to your database and perform queries, use `@an5/adapters`:
@@ -169,6 +189,49 @@ model Order {
 }
 ```
 
+Views are declared with the same field syntax, so generated clients can type their
+rows, plus the `SELECT` that defines them. A view is read-only: writes are not
+generated, and `db:push`/`db:migrate` create the view after the tables it reads —
+and after any view it reads. `db:pull` writes a database view back as a `view`
+block, with its columns and the SQL body from the catalog. `db:cleanup` drops
+views that are no longer in the schema, before the tables they might read.
+
+`@@sql` holds the `SELECT` body; a full `CREATE VIEW ... AS ...` statement pasted
+from a catalog is reduced to that body, so its header and object name are not
+repeated in the generated DDL.
+
+Generated clients expose a view through a read-only client — `ViewClient` in
+TypeScript, Python, .NET, Java and Kotlin, `ViewModelClient` in Swift, and
+`ViewClient[T]` in Go and Rust. Those types have the read methods only, so a write
+to a view is rejected at compile time rather than by the database.
+
+```an5
+view ActiveUser {
+  id    NVARCHAR(1000)
+  email NVARCHAR(255)
+
+  @@map("active_users")
+  @@sql("SELECT id, email FROM users WHERE active = 1")
+}
+```
+
+A longer query can be written over several lines with triple quotes; the indentation
+shared by the SQL lines is removed before it reaches the database:
+
+```an5
+view ActiveUser {
+  id    NVARCHAR(1000)
+  email NVARCHAR(255)
+
+  @@map("active_users")
+  @@sql("""
+    SELECT id, email
+    FROM users
+    WHERE active = 1
+  """)
+}
+```
+
 ## License
 
 MIT

package/dist/cleanup.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/cleanup.js

@@ -0,0 +1,177 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const adapters_1 = require("@an5/adapters");
+const config_1 = require("./generator/src/config");
+const provider_support_1 = require("./provider-support");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const rootDir = process.cwd();
+const { config, outputs } = (0, config_1.loadConfig)();
+const schemaDir = outputs.schemaDir;
+let _adapter = null;
+async function getDb() {
+    if (!_adapter) {
+        _adapter = new adapters_1.An5Adapter({ connectionString: (0, config_1.resolveConnectionString)(config, process.env, "db:cleanup") });
+        await _adapter.$connect();
+    }
+    return _adapter;
+}
+/**
+ * Prints why a command cannot run against this provider and exits.
+ *
+ * The decision and the wording live in `./provider-support`, which stays free of Node
+ * globals so it can be imported and tested anywhere; only the command files, which
+ * are Node programs, do the exiting.
+ */
+function refuseIfNotSqlServer(provider, command) {
+    const message = (0, provider_support_1.sqlServerOnlyError)(provider, command);
+    if (message === null)
+        return;
+    console.error(message);
+    process.exit(1);
+}
+/**
+ * The tables and views the schema files declare, lower-cased.
+ *
+ * SQL Server compares object names case-insensitively in the default collation,
+ * so `Users` and `users` are the same object here; a case-sensitive comparison
+ * would drop a table the schema still declares.
+ */
+function declaredObjects(schemaText) {
+    const tables = new Set();
+    const views = new Set();
+    let block = null;
+    let blockName = '';
+    for (const rawLine of schemaText.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('//'))
+            continue;
+        const start = /^(model|view)\s+(\w+)\s*\{/.exec(line);
+        if (start) {
+            block = start[1];
+            blockName = start[2] ?? '';
+            if (block === 'model')
+                tables.add(blockName.toLowerCase() + 's');
+            else
+                views.add(blockName.toLowerCase() + 's');
+            continue;
+        }
+        if (line === '}') {
+            block = null;
+            continue;
+        }
+        const mapped = /^@@map\(\s*"([^"]+)"\s*\)/.exec(line);
+        if (mapped?.[1]) {
+            // A mapped name replaces the default one, but `@@map` outside a block is
+            // still read as a table name: older schema files may have it there.
+            const target = block === 'view' ? views : tables;
+            target.add(mapped[1].toLowerCase());
+        }
+    }
+    return { tables, views };
+}
+/** Quotes a catalog identifier, doubling `]` the way T-SQL expects. */
+function quoteName(name) {
+    return `[${name.replace(/]/g, ']]')}]`;
+}
+async function cleanup() {
+    // Drops tables by comparing sys.tables with the schema files, so a non-SQL
+    // Server connection string is a mistake worth naming first.
+    refuseIfNotSqlServer((0, config_1.providerFromConfig)(config, process.env), "db:cleanup");
+    console.log("🧹 Starting database cleanup...");
+    let schemaText = "";
+    if (fs_1.default.existsSync(schemaDir)) {
+        const files = fs_1.default.readdirSync(schemaDir).filter(f => f.endsWith(".an5"));
+        for (const file of files) {
+            schemaText += fs_1.default.readFileSync(path_1.default.join(schemaDir, file), "utf8") + "\n";
+        }
+    }
+    else {
+        const schemaPath = path_1.default.join(__dirname, "schema.an5");
+        if (fs_1.default.existsSync(schemaPath)) {
+            schemaText = fs_1.default.readFileSync(schemaPath, "utf8");
+        }
+        else {
+            console.error("No schema found!");
+            process.exit(1);
+        }
+    }
+    const { tables: validTables, views: validViews } = declaredObjects(schemaText);
+    // Also include the capitalization variations from an5Metadata if we can,
+    // but schema.an5 is the source of truth.
+    console.log("Valid tables from schema:", Array.from(validTables));
+    console.log("Valid views from schema:", Array.from(validViews));
+    const dbTables = await (await getDb()).$queryRawUnsafe(`
+    SELECT name FROM sys.tables WHERE is_ms_shipped = 0
+  `);
+    const dbViews = await (await getDb()).$queryRawUnsafe(`
+    SELECT name FROM sys.views WHERE is_ms_shipped = 0
+  `);
+    const tablesToDrop = dbTables
+        .map(t => t.name)
+        .filter(name => !validTables.has(name.toLowerCase()));
+    const viewsToDrop = dbViews
+        .map(v => v.name)
+        .filter(name => !validViews.has(name.toLowerCase()));
+    // Views go first: one of them may read a table that is about to be dropped, and
+    // an orphan view is exactly what this command is meant to remove.
+    if (viewsToDrop.length > 0) {
+        console.log("Views to be DROPPED:", viewsToDrop);
+        for (const view of viewsToDrop) {
+            console.log(`Dropping view [${view}]...`);
+            try {
+                await (await getDb()).$executeRawUnsafe(`DROP VIEW IF EXISTS ${quoteName(view)}`);
+                console.log(`✅ Dropped [${view}]`);
+            }
+            catch (err) {
+                console.error(`❌ Failed to drop view [${view}]: ${err.message}`);
+            }
+        }
+    }
+    if (tablesToDrop.length === 0) {
+        console.log(viewsToDrop.length === 0
+            ? "✅ No extra tables found. Database is clean."
+            : "✅ No extra tables found.");
+        console.log("✅ Cleanup completed.");
+        process.exit(0);
+    }
+    console.log("Tables to be DROPPED:", tablesToDrop);
+    for (const table of tablesToDrop) {
+        console.log(`Dropping table [${table}]...`);
+        try {
+            // We need to handle foreign key constraints.
+            // For a thorough cleanup, we might need to drop constraints first.
+            // But for now, we'll try a simple DROP TABLE.
+            await (await getDb()).$executeRawUnsafe(`DROP TABLE ${quoteName(table)}`);
+            console.log(`✅ Dropped [${table}]`);
+        }
+        catch (err) {
+            console.error(`❌ Failed to drop [${table}]: ${err.message}`);
+            if (err.message.includes("FOREIGN KEY constraint")) {
+                console.log(`Attempting to find and drop constraints for [${table}]...`);
+                const constraints = await (await getDb()).$queryRawUnsafe(`
+            SELECT fk.name AS constraint_name, OBJECT_NAME(fk.parent_object_id) AS table_name
+            FROM sys.foreign_keys AS fk
+            WHERE OBJECT_NAME(fk.referenced_object_id) = @p_0 OR OBJECT_NAME(fk.parent_object_id) = @p_0
+          `, table);
+                for (const c of constraints) {
+                    console.log(`Dropping constraint [${c.constraint_name}] on [${c.table_name}]...`);
+                    await (await getDb()).$executeRawUnsafe(`ALTER TABLE ${quoteName(c.table_name)} DROP CONSTRAINT ${quoteName(c.constraint_name)}`);
+                }
+                // Try dropping again
+                await (await getDb()).$executeRawUnsafe(`DROP TABLE ${quoteName(table)}`);
+                console.log(`✅ Dropped [${table}] after removing constraints.`);
+            }
+        }
+    }
+    console.log("✅ Cleanup completed.");
+    process.exit(0);
+}
+cleanup().catch(err => {
+    console.error("❌ Cleanup failed:", err);
+    process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(rawArgs?: string[]): void;

package/dist/cli.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function printHelp() {
+    console.log(`AN5 ORM CLI
+
+Usage:
+  an5 <command> [options]
+  npx @an5/orm <command> [options]
+
+Commands:
+  generate, codegen          Generate client code from .an5 schemas
+  db:push, push              Push schema directly to database
+  db:pull, pull              Pull database schema into .an5 files
+  db:migrate, migrate        Manage database migrations:
+    diff                       Show differences between schema and database
+    generate                   Generate a new migration script
+    apply [--preview]          Apply pending migrations
+    rollback [--preview]       Roll back applied migrations
+    status                     View migration status
+  db:seed, seed              Run project seed script (seed.ts / seed.js)
+  db:cleanup, cleanup        Clean up database tables
+
+Options:
+  -v, --version              Show version number
+  -h, --help                 Show help
+`);
+}
+function printVersion() {
+    try {
+        const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '..', 'package.json'), 'utf8'));
+        console.log(`@an5/orm v${pkg.version}`);
+    }
+    catch {
+        console.log('@an5/orm');
+    }
+}
+function resolveCommandScript(baseName) {
+    // If running from dist/cli.js, command files are right next to it
+    const distCandidate = path_1.default.join(__dirname, `${baseName}.js`);
+    if (fs_1.default.existsSync(distCandidate)) {
+        return distCandidate;
+    }
+    if (baseName === 'generator') {
+        const genDist = path_1.default.join(__dirname, 'generator', 'src', 'index.js');
+        if (fs_1.default.existsSync(genDist))
+            return genDist;
+        const genTs = path_1.default.join(__dirname, '..', 'generator', 'src', 'index.ts');
+        if (fs_1.default.existsSync(genTs))
+            return genTs;
+    }
+    const rootTs = path_1.default.join(__dirname, '..', `${baseName}.ts`);
+    if (fs_1.default.existsSync(rootTs)) {
+        return rootTs;
+    }
+    const localTs = path_1.default.join(__dirname, `${baseName}.ts`);
+    if (fs_1.default.existsSync(localTs)) {
+        return localTs;
+    }
+    return distCandidate;
+}
+function runScript(scriptPath, args) {
+    const isTs = scriptPath.endsWith('.ts');
+    const runner = isTs ? (process.platform === 'win32' ? 'npx.cmd' : 'npx') : process.execPath;
+    const runnerArgs = isTs ? ['tsx', scriptPath, ...args] : [scriptPath, ...args];
+    const result = (0, child_process_1.spawnSync)(runner, runnerArgs, {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (result.error) {
+        console.error(`❌ Failed to execute command: ${result.error.message}`);
+        process.exit(1);
+    }
+    process.exit(result.status ?? (result.signal ? 1 : 0));
+}
+function main(rawArgs = process.argv.slice(2)) {
+    const [firstArg, ...rest] = rawArgs;
+    if (!firstArg || firstArg === '--help' || firstArg === '-h' || firstArg === 'help') {
+        printHelp();
+        process.exit(0);
+    }
+    if (firstArg === '--version' || firstArg === '-v' || firstArg === 'version') {
+        printVersion();
+        process.exit(0);
+    }
+    // Handle db:migrate:... shorthand (e.g. db:migrate:apply -> migrate apply)
+    if (firstArg.startsWith('db:migrate:')) {
+        const sub = firstArg.slice('db:migrate:'.length);
+        const script = resolveCommandScript('migrate');
+        runScript(script, [sub, ...rest]);
+        return;
+    }
+    switch (firstArg) {
+        case 'generate':
+        case 'codegen':
+        case 'g': {
+            const script = resolveCommandScript('generator');
+            runScript(script, rest);
+            break;
+        }
+        case 'db:push':
+        case 'push': {
+            const script = resolveCommandScript('push');
+            runScript(script, rest);
+            break;
+        }
+        case 'db:pull':
+        case 'pull': {
+            const script = resolveCommandScript('pull');
+            runScript(script, rest);
+            break;
+        }
+        case 'db:seed':
+        case 'seed': {
+            const script = resolveCommandScript('seed');
+            runScript(script, rest);
+            break;
+        }
+        case 'db:cleanup':
+        case 'cleanup': {
+            const script = resolveCommandScript('cleanup');
+            runScript(script, rest);
+            break;
+        }
+        case 'db:migrate':
+        case 'migrate': {
+            const script = resolveCommandScript('migrate');
+            runScript(script, rest);
+            break;
+        }
+        default: {
+            console.error(`Unknown command: "${firstArg}"`);
+            console.error('Run "an5 --help" for a list of available commands.');
+            process.exit(1);
+        }
+    }
+}
+if (require.main === module) {
+    main();
+}

package/dist/generator/src/attributes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Reading `@attribute(...)` arguments from a `.an5` field or model line.
+ *
+ * The schema used to be read with regexes such as `/@default\((.*)\)/`, which
+ * ran to the *last* `)` on the line. A field with `@default(now())` followed by
+ * `@description("...")` therefore had `now()) @description("..."` as its default
+ * expression, and `db:push` emitted SQL no database accepts. The closing
+ * parenthesis has to be the one that matches the opening one — parentheses nest
+ * (`now()`, `uuid()`, `lower(...)`) and quoted strings may contain both.
+ *
+ * These helpers only read attributes; they do not validate the schema language.
+ */
+/** Whether `line` has the attribute, with or without arguments. */
+export declare function hasAttribute(line: string, name: string): boolean;
+/**
+ * The raw argument text of the first `name(...)` on `line`.
+ *
+ * Returns `undefined` when the attribute is absent, or when it is written
+ * without parentheses. The returned text keeps its quotes, so callers decide
+ * whether they are reading a string, a number or an expression.
+ */
+export declare function attributeArgs(line: string, name: string): string | undefined;
+/** Strips one pair of surrounding double quotes, if present. */
+export declare function unquote(value: string | undefined): string | undefined;
+/**
+ * Splits schema text into logical lines, keeping a triple-quoted `@@sql` body on
+ * one line.
+ *
+ * The parsers read a schema line by line. Without this, a multi-line view body
+ * would end the directive at its first newline and the rest of the `SELECT`
+ * would be read as fields of the view. Newlines inside the quotes are preserved;
+ * only the split points change.
+ */
+export declare function splitSchemaLines(text: string): string[];
+/**
+ * Reads a named string option from an attribute argument list, e.g.
+ * `map: "UQ_users_email"` in `@unique(map: "UQ_users_email")`.
+ */
+export declare function stringOption(args: string | undefined, key: string): string | undefined;
+/** Reads a named field-list option, e.g. `include: [email, tenantId]`. */
+export declare function fieldListOption(args: string | undefined, key: string): string[] | undefined;
+/** One `@@unique` or `@@index` directive, with the options it accepts. */
+export interface IndexDirective {
+    fields: string[];
+    name?: string;
+    includeFields?: string[];
+    filter?: string;
+    options?: string;
+}
+/**
+ * Parses the inside of `@@unique([a, b], map: "…", include: […], …)`.
+ *
+ * The directive is the one place a schema can carry raw SQL (`filter`,
+ * `options`), so its argument list is balanced rather than cut at the first
+ * `)`. A filter such as `(deletedAt IS NULL)` used to truncate the directive.
+ */
+export declare function parseIndexDirective(args: string | undefined): IndexDirective | null;