@an5/orm 1.3.2 → 1.3.4

package/dist/generator/src/swift-generator.js

@@ -569,12 +569,13 @@ public enum An5Config {
         let accessors = models.map((model) => ({
             property: SwiftGenerator.toLowerCamelCase(model.name),
             name: model.name,
+            isView: model.isView === true,
         }));
         const unique = new Map();
         for (const entry of accessors) {
             const key = SwiftGenerator.toLowerCamelCase(entry.name);
             if (!unique.has(key))
-                unique.set(key, { property: key, name: entry.name });
+                unique.set(key, { property: key, name: entry.name, isView: entry.isView });
         }
         let content = `// This file is auto-generated. Do not edit deliberately.
 import Foundation
@@ -669,6 +670,54 @@ public struct ModelClient<T> {
     }
 }
 
+/// A read-only, typed client for one view.
+///
+/// The name avoids the runtime's own \`ViewClient\`, which is wrapped here: the runtime
+/// returns \`Row\` values and this maps them to the generated model. There are no write
+/// methods, so writing through a view does not compile.
+public struct ViewModelClient<T> {
+
+    private let client: ViewClient
+    private let read: (Row) -> T
+
+    init(view: ViewClient, read: @escaping (Row) -> T) {
+        self.client = view
+        self.read = read
+    }
+
+    /// The view this client reads.
+    public var view: String { client.view }
+
+    public func findMany() throws -> [T] { try client.findMany().map { read($0) } }
+
+    public func findMany(_ query: Query) throws -> [T] { try client.findMany(query).map { read($0) } }
+
+    public func findMany(filter: Where) throws -> [T] { try client.findMany(filter: filter).map { read($0) } }
+
+    public func findFirst(filter: Where) throws -> T? { try client.findFirst(filter: filter).map { read($0) } }
+
+    public func findUnique(filter: Where) throws -> T? { try client.findUnique(filter: filter).map { read($0) } }
+
+    public func count(_ filter: Where? = nil) throws -> Int { try client.count(filter) }
+
+    /// One row of aggregate values, keyed \`_count\`, \`_sum_<field>\` and so on.
+    public func aggregate(_ aggregate: Aggregate) throws -> Row { try client.aggregate(aggregate) }
+
+    /// One row per group, each carrying the group's count and aggregates.
+    public func groupBy(_ aggregate: Aggregate) throws -> [Row] { try client.groupBy(aggregate) }
+
+    /// The rows nearest a vector.
+    public func vectorSearch(
+        _ vector: [Double],
+        take: Int = 10,
+        filter: Where? = nil,
+        vectorField: String = "embedding",
+        metric: DistanceMetric = .cosine
+    ) throws -> [T] {
+        try client.vectorSearch(vector, take: take, filter: filter, vectorField: vectorField, metric: metric).map { read($0) }
+    }
+}
+
 /// The AN5 entry point: one typed client per model, over one connection.
 ///
 /// \`\`\`
@@ -681,7 +730,7 @@ public final class An5Db {
     public let an5: An5Adapter
 
 ${Array.from(unique.values())
-            .map((entry) => `    /// Queries for \`${entry.name}\`.\n    public let ${entry.property}: ModelClient<${entry.name}>`)
+            .map((entry) => `    /// ${entry.isView ? 'Reads' : 'Queries'} for \`${entry.name}\`.\n    public let ${entry.property}: ${entry.isView ? 'ViewModelClient' : 'ModelClient'}<${entry.name}>`)
             .join('\n\n')}
 
     /// Opens a database from a connection string, registering this schema with the runtime.
@@ -704,7 +753,9 @@ ${Array.from(unique.values())
     public init(adapter: An5Adapter) {
         self.an5 = adapter
 ${Array.from(unique.values())
-            .map((entry) => `        self.${entry.property} = ModelClient(\n            table: adapter.table("${entry.name}"),\n            read: { ${entry.name}(row: $0) },\n            write: { $0.values })`)
+            .map((entry) => entry.isView
+            ? `        self.${entry.property} = ViewModelClient(\n            view: adapter.view("${entry.name}"),\n            read: { ${entry.name}(row: $0) })`
+            : `        self.${entry.property} = ModelClient(\n            table: adapter.table("${entry.name}"),\n            read: { ${entry.name}(row: $0) },\n            write: { $0.values })`)
             .join('\n')}
     }
 

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

@@ -33,6 +33,16 @@ export interface Model {
     relations: Relation[];
     compoundUniques?: string[][];
     description?: string;
+    /**
+     * A `view` block rather than a `model`.
+     *
+     * Views are described with the same field syntax so generated clients can type
+     * their rows, but they are read-only and their DDL comes from `viewSql` rather
+     * than from the fields.
+     */
+    isView?: boolean;
+    /** The `SELECT` body of `@@sql("...")`; required for a view. */
+    viewSql?: string;
 }
 /**
  * The table name as it goes into the generated metadata.

package/dist/generator/src/view-order.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Orders views so one that reads another is created after it.
+ *
+ * Tables are created before any view, but views are not all independent of each
+ * other: a summary view may select from a detail view. PostgreSQL and SQLite
+ * reject `CREATE VIEW` when the referenced relation does not exist yet, so
+ * declaration order in the schema file is not enough.
+ *
+ * The reference check is deliberately textual: a full SQL parser would be the
+ * only way to be exact, and a false positive here merely reorders two independent
+ * views. Missing an edge leaves the old declaration order, which is what this
+ * function improves on rather than replaces.
+ */
+/** A view plus every identifier its SQL may use to reference it. */
+export interface ViewOrderEntry {
+    /** Physical name, model name, or both; qualified names are reduced to their last part too. */
+    names: readonly string[];
+    sql: string;
+}
+export interface ViewOrderResult<T> {
+    ordered: T[];
+    /** True when the references form a cycle, which no view definition can satisfy. */
+    cyclic: boolean;
+}
+/**
+ * Stable topological sort of `views`.
+ *
+ * Kahn's algorithm in declaration order, so a schema that was already correct is
+ * left untouched. A cycle cannot be created by a database view definition; when
+ * one is detected the remaining views keep their original order and the caller
+ * can decide whether to warn or let the database report the error.
+ */
+export declare function orderViewsByDependency<T extends ViewOrderEntry>(views: readonly T[]): ViewOrderResult<T>;

package/dist/generator/src/view-order.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Orders views so one that reads another is created after it.
+ *
+ * Tables are created before any view, but views are not all independent of each
+ * other: a summary view may select from a detail view. PostgreSQL and SQLite
+ * reject `CREATE VIEW` when the referenced relation does not exist yet, so
+ * declaration order in the schema file is not enough.
+ *
+ * The reference check is deliberately textual: a full SQL parser would be the
+ * only way to be exact, and a false positive here merely reorders two independent
+ * views. Missing an edge leaves the old declaration order, which is what this
+ * function improves on rather than replaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orderViewsByDependency = orderViewsByDependency;
+/** Escapes a name for a regular expression. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Identifiers in `sql` lose their quoting so `[s].[v]`, `"s"."v"` and `s.v` compare alike. */
+function unquoteIdentifiers(sql) {
+    return sql.replace(/[[\]"`]/g, '');
+}
+function mentions(sql, name) {
+    if (!name)
+        return false;
+    const pattern = new RegExp(`(^|[^A-Za-z0-9_$])${escapeRegExp(name)}([^A-Za-z0-9_$]|$)`, 'i');
+    return pattern.test(sql);
+}
+/** Every way a view in this schema can be referenced: `schema.name`, `name`, or a mapped name. */
+function referenceNames(names) {
+    const result = new Set();
+    for (const name of names) {
+        const trimmed = name.trim();
+        if (!trimmed)
+            continue;
+        result.add(trimmed);
+        const dot = trimmed.lastIndexOf('.');
+        if (dot >= 0 && dot < trimmed.length - 1)
+            result.add(trimmed.slice(dot + 1));
+    }
+    return Array.from(result);
+}
+/**
+ * Stable topological sort of `views`.
+ *
+ * Kahn's algorithm in declaration order, so a schema that was already correct is
+ * left untouched. A cycle cannot be created by a database view definition; when
+ * one is detected the remaining views keep their original order and the caller
+ * can decide whether to warn or let the database report the error.
+ */
+function orderViewsByDependency(views) {
+    if (views.length < 2)
+        return { ordered: [...views], cyclic: false };
+    const references = views.map((view) => referenceNames(view.names));
+    const normalizedSql = views.map((view) => unquoteIdentifiers(view.sql));
+    const byName = new Map();
+    const owners = new Map();
+    for (let index = 0; index < references.length; index += 1) {
+        for (const name of references[index] ?? []) {
+            const key = name.toLowerCase();
+            const existing = owners.get(key);
+            if (existing)
+                existing.add(index);
+            else
+                owners.set(key, new Set([index]));
+        }
+    }
+    // A bare `summary` is ambiguous when two schemas both have one; a dependency
+    // guessed from it could reorder unrelated views or invent a cycle. Only names
+    // that identify one view take part.
+    for (const [name, indices] of owners) {
+        if (indices.size === 1)
+            byName.set(name, Array.from(indices));
+    }
+    const dependencies = views.map(() => new Set());
+    for (let index = 0; index < views.length; index += 1) {
+        for (const [name, candidates] of byName) {
+            if (!mentions(normalizedSql[index] ?? '', name))
+                continue;
+            for (const candidate of candidates) {
+                if (candidate !== index)
+                    dependencies[index]?.add(candidate);
+            }
+        }
+    }
+    const dependents = views.map(() => []);
+    const indegree = views.map((_, index) => dependencies[index]?.size ?? 0);
+    for (let index = 0; index < dependencies.length; index += 1) {
+        for (const dependency of dependencies[index] ?? []) {
+            dependents[dependency]?.push(index);
+        }
+    }
+    const ordered = [];
+    const queued = new Set();
+    const ready = [];
+    for (let index = 0; index < views.length; index += 1) {
+        if ((indegree[index] ?? 0) === 0)
+            ready.push(index);
+    }
+    while (ready.length > 0) {
+        const index = ready.shift();
+        if (queued.has(index))
+            continue;
+        queued.add(index);
+        ordered.push(views[index]);
+        for (const dependent of dependents[index] ?? []) {
+            const remaining = (indegree[dependent] ?? 0) - 1;
+            indegree[dependent] = remaining;
+            if (remaining === 0)
+                ready.push(dependent);
+        }
+    }
+    const cyclic = ordered.length !== views.length;
+    // A cycle is preserved as written, which is the only order the caller can act
+    // on; dropping the views would silently change the schema.
+    for (let index = 0; index < views.length; index += 1) {
+        if (!queued.has(index))
+            ordered.push(views[index]);
+    }
+    return { ordered, cyclic };
+}

package/dist/migrate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * an5Orm Migration Tool
+ * Compares schema files with database and generates migration SQL.
+ *
+ * Usage:
+ *   npx tsx migrate.ts diff       # Show differences
+ *   npx tsx migrate.ts generate   # Generate migration file
+ *   npx tsx migrate.ts apply      # Apply pending migrations
+ *   npx tsx migrate.ts rollback [steps|--to file] # Roll back applied migrations
+ *   npx tsx migrate.ts status     # Show migration status
+ */
+import 'dotenv/config';