@an5/orm 1.3.2 → 1.3.3

package/generator/src/swift-generator.ts

@@ -624,11 +624,12 @@ public enum An5Config {
     let accessors = models.map((model) => ({
       property: SwiftGenerator.toLowerCamelCase(model.name),
       name: model.name,
+      isView: model.isView === true,
     }));
-    const unique = new Map<string, { property: string; name: string }>();
+    const unique = new Map<string, { property: string; name: string; isView: boolean }>();
     for (const entry of accessors) {
       const key = SwiftGenerator.toLowerCamelCase(entry.name);
-      if (!unique.has(key)) unique.set(key, { property: key, name: entry.name });
+      if (!unique.has(key)) unique.set(key, { property: key, name: entry.name, isView: entry.isView });
     }
 
     let content = `// This file is auto-generated. Do not edit deliberately.
@@ -724,6 +725,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.
 ///
 /// \`\`\`
@@ -736,7 +785,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.
@@ -761,7 +810,9 @@ ${Array.from(unique.values())
 ${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 })`
+      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/generator/src/types.ts

@@ -36,6 +36,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;
 }
 
 /**

package/generator/src/view-order.ts

@@ -0,0 +1,133 @@
+/**
+ * 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;
+}
+
+/** Escapes a name for a regular expression. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Identifiers in `sql` lose their quoting so `[s].[v]`, `"s"."v"` and `s.v` compare alike. */
+function unquoteIdentifiers(sql: string): string {
+  return sql.replace(/[[\]"`]/g, '');
+}
+
+function mentions(sql: string, name: string): boolean {
+  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: readonly string[]): string[] {
+  const result = new Set<string>();
+  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.
+ */
+export function orderViewsByDependency<T extends ViewOrderEntry>(views: readonly T[]): ViewOrderResult<T> {
+  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<string, number[]>();
+  const owners = new Map<string, Set<number>>();
+  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<number>());
+  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: number[][] = 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: T[] = [];
+  const queued = new Set<number>();
+  const ready: number[] = [];
+  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() as number;
+    if (queued.has(index)) continue;
+    queued.add(index);
+    ordered.push(views[index] as T);
+    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] as T);
+  }
+
+  return { ordered, cyclic };
+}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@an5/orm",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "The lightweight ORM for SQL Server with support for TypeScript, Python, .NET (C#), Go, Rust, Java, Kotlin, and Swift.",
   "license": "MIT",
+  "bin": {
+    "an5": "./dist/cli.js",
+    "an5-orm": "./dist/cli.js",
+    "orm": "./dist/cli.js"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -29,25 +34,25 @@
     "url": "https://github.com/an5ORM/an5Orm.git"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p generator/tsconfig.json && node scripts/normalize-eol.js",
+    "build": "tsc -p tsconfig.json && tsc -p generator/tsconfig.json && tsc -p tsconfig.cli.json && node scripts/normalize-eol.js",
     "typecheck:cli": "tsc -p tsconfig.cli.json",
     "pretest": "npm run build",
     "prepack": "npm run build && npm run verify:pack",
     "prepublishOnly": "npm run verify:pack",
-    "generate": "npx tsx generator/src/index.ts",
-    "db:push": "npx tsx push.ts",
-    "db:pull": "npx tsx pull.ts",
-    "db:seed": "npx tsx seed.ts",
-    "db:cleanup": "npx tsx cleanup.ts",
-    "db:migrate": "npx tsx migrate.ts",
-    "db:migrate:diff": "npx tsx migrate.ts diff",
-    "db:migrate:generate": "npx tsx migrate.ts generate",
-    "db:migrate:apply": "npx tsx migrate.ts apply",
-    "db:migrate:rollback": "npx tsx migrate.ts rollback",
-    "db:migrate:status": "npx tsx migrate.ts status",
+    "generate": "node dist/cli.js generate",
+    "db:push": "node dist/cli.js db:push",
+    "db:pull": "node dist/cli.js db:pull",
+    "db:seed": "node dist/cli.js db:seed",
+    "db:cleanup": "node dist/cli.js db:cleanup",
+    "db:migrate": "node dist/cli.js db:migrate",
+    "db:migrate:diff": "node dist/cli.js db:migrate diff",
+    "db:migrate:generate": "node dist/cli.js db:migrate generate",
+    "db:migrate:apply": "node dist/cli.js db:migrate apply",
+    "db:migrate:rollback": "node dist/cli.js db:migrate rollback",
+    "db:migrate:status": "node dist/cli.js db:migrate status",
     "release:cli": "npx tsx scripts/release-cli.ts",
     "release": "node scripts/release.js",
-    "test": "npm run typecheck:cli && node test/smoke.test.js && node test/unit.test.js && node test/generator-regressions.test.js && node --test test/config.test.js && node --test test/provider-types.test.js && node --test test/provider-push.test.js && node --test test/provider-push.sqlite.test.js && node --test test/type-kinds.test.js && node --test test/declarations.test.js && node --test test/version-sync.test.js && node --test test/query-semantics.test.js",
+    "test": "npm run typecheck:cli && node test/smoke.test.js && node test/unit.test.js && node test/generator-regressions.test.js && node --test test/config.test.js && node --test test/cli.test.js && node --test test/provider-types.test.js && node --test test/provider-push.test.js && node --test test/provider-push.sqlite.test.js && node --test test/type-kinds.test.js && node --test test/declarations.test.js && node --test test/version-sync.test.js && node --test test/query-semantics.test.js",
     "test:unit": "node test/unit.test.js",
     "test:generator": "npm run generate && node test/generator.test.js",
     "test:generator:regressions": "node test/generator-regressions.test.js",