@an5/orm 1.3.2 → 1.3.3

package/generator/src/parser.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { Model, Field, Relation } from './types';
+import { attributeArgs, hasAttribute, parseIndexDirective, splitSchemaLines, unquote } from './attributes';
 import {
   DEFAULT_PROVIDER,
   FieldTypeError,
@@ -37,10 +38,25 @@ interface PendingModelRef {
   line: string;
 }
 
+/**
+ * A field inside a `view` whose type matched nothing.
+ *
+ * A view's fields describe the shape of a result set, never a relation, so the
+ * decision made for models — "a name used by another block is a relation" — does
+ * not apply. The reference is kept until every block has been read so the error
+ * can still suggest a close model name.
+ */
+interface PendingViewRef {
+  view: string;
+  field: string;
+  type: string;
+}
+
 export class SchemaParser {
   private schemaText: string = '';
   private issues: FieldTypeIssue[] = [];
   private modelRefs: PendingModelRef[] = [];
+  private viewRefs: PendingViewRef[] = [];
   private models: Model[] = [];
 
   /**
@@ -55,9 +71,10 @@ export class SchemaParser {
   public async parse(): Promise<Model[]> {
     this.issues = [];
     this.modelRefs = [];
+    this.viewRefs = [];
     this.models = [];
     this.loadSchema();
-    const lines = this.schemaText.split('\n');
+    const lines = splitSchemaLines(this.schemaText);
     const models: Model[] = [];
     let currentModel: Model | null = null;
 
@@ -84,6 +101,22 @@ export class SchemaParser {
         continue;
       }
 
+      const viewHeaderMatch = line.match(/^view\s+(\w+)\s*\{/);
+      if (viewHeaderMatch) {
+        const viewName = viewHeaderMatch[1];
+        currentModel = {
+          name: viewName,
+          tableName: viewName.toLowerCase() + 's',
+          schemaName: this.provider === 'mssql' ? 'dbo' : '',
+          provider: this.provider,
+          fields: [],
+          relations: [],
+          isView: true,
+        };
+        models.push(currentModel);
+        continue;
+      }
+
       if (line === '}') {
         currentModel = null;
         continue;
@@ -97,6 +130,12 @@ export class SchemaParser {
     this.models = models;
     this.resolveModelRefs();
 
+    const missingSql = models.filter((model) => model.isView && !model.viewSql?.trim());
+    if (missingSql.length > 0) {
+      const names = missingSql.map((model) => `"${model.name}"`).join(', ');
+      throw new Error(`View ${names} must declare @@sql("SELECT ...").`);
+    }
+
     // Every bad type is reported at once, so one pass over the schema is enough
     // instead of re-running the generator after every line.
     if (this.issues.length > 0) {
@@ -119,32 +158,42 @@ export class SchemaParser {
   }
 
   private parseModelLine(line: string, model: Model) {
+    if (line.startsWith('@@sql') || line.startsWith('@@definition')) {
+      // `@@definition` is accepted as an alias: the directive names a SQL body,
+      // and both spellings are unambiguous.
+      const attribute = line.startsWith('@@sql') ? '@@sql' : '@@definition';
+      if (model.isView) {
+        const sql = unquote(attributeArgs(line, attribute));
+        if (sql !== undefined) model.viewSql = sql.trim();
+      }
+      return;
+    }
     if (line.startsWith('@@map')) {
-      const mapMatch = line.match(/@@map\("(.+)"\)/);
-      if (mapMatch) model.tableName = mapMatch[1];
+      const mapped = unquote(attributeArgs(line, '@@map'));
+      if (mapped) model.tableName = mapped;
       return;
     }
     if (line.startsWith('@@schema')) {
-      // `(.*)` rather than `(.+)`: `@@schema("")` is how a model says "no
-      // schema", needed for databases that have no schema concept. With `(.+)`
-      // the empty string does not match, the directive is silently ignored and
-      // the model keeps `dbo`.
-      const schemaMatch = line.match(/@@schema\("(.*)"\)/);
-      if (schemaMatch) model.schemaName = schemaMatch[1].trim();
+      // An empty string is meaningful: `@@schema("")` says "no schema", needed
+      // for databases that have no schema concept. It must not be dropped as if
+      // the directive were absent.
+      const declared = unquote(attributeArgs(line, '@@schema'));
+      if (declared !== undefined) model.schemaName = declared.trim();
       return;
     }
     if (line.startsWith('@@unique')) {
-      const uniqueMatch = line.match(/@@unique\(\[([\w,\s]+)\]\)/);
-      if (uniqueMatch) {
-        const fields = uniqueMatch[1].split(',').map(f => f.trim());
+      // Constraints describe stored tables; a view's shape comes from its SQL.
+      if (model.isView) return;
+      const parsed = parseIndexDirective(attributeArgs(line, '@@unique'));
+      if (parsed) {
         model.compoundUniques = model.compoundUniques || [];
-        model.compoundUniques.push(fields);
+        model.compoundUniques.push(parsed.fields);
       }
       return;
     }
     if (line.startsWith('@@description')) {
-      const descMatch = line.match(/@@description\("(.+)"\)/);
-      if (descMatch) model.description = descMatch[1];
+      const description = unquote(attributeArgs(line, '@@description'));
+      if (description !== undefined) model.description = description;
       return;
     }
     if (line.startsWith('@@')) return;
@@ -158,16 +207,19 @@ export class SchemaParser {
     // later at the database layer, in a message unrelated to the schema.
     const resolved = resolveFieldType(head.type, this.provider);
     if (!resolved) {
+      if (model.isView) {
+        // A view's fields are columns of a result set, never relations.
+        this.viewRefs.push({ view: model.name, field: head.name, type: head.type });
+        return;
+      }
       this.modelRefs.push({ model, name: head.name, type: head.type, isArray: head.isArray, isOptional: head.isOptional, line });
       return;
     }
 
-    const hasDefault = line.includes('@default') || line.includes('@updatedAt') || line.includes('@id');
-    const isId = line.includes('@id');
-    let description: string | undefined;
-    const descMatch = line.match(/@description\("(.+)"\)/);
-    if (descMatch) description = descMatch[1];
-    model.fields.push({ name: head.name, type: resolved.ts, sqlType: head.type, isOptional: head.isOptional, hasDefault, isId, description });
+    const hasDefault = hasAttribute(line, '@default') || hasAttribute(line, '@updatedAt') || hasAttribute(line, '@id');
+    const isId = hasAttribute(line, '@id');
+    const description = unquote(attributeArgs(line, '@description'));
+    model.fields.push({ name: head.name, type: resolved.ts, sqlType: head.type, isOptional: head.isOptional, hasDefault, isId, ...(description !== undefined ? { description } : {}) });
   }
 
   /**
@@ -182,25 +234,45 @@ export class SchemaParser {
    */
   private resolveModelRefs() {
     const modelNames = this.models.map((model) => model.name);
+    const tableNames = this.models.filter((model) => !model.isView).map((model) => model.name);
+    const viewNames = new Set(this.models.filter((model) => model.isView).map((model) => model.name));
+
+    for (const ref of this.viewRefs) {
+      this.issues.push({
+        path: `${ref.view}.${ref.field}`,
+        message: unknownFieldTypeMessage(ref.type, this.provider, modelNames),
+      });
+    }
+    this.viewRefs = [];
 
     for (const ref of this.modelRefs) {
-      if (!modelNames.includes(ref.type)) {
+      if (viewNames.has(ref.type)) {
+        // A relation carries a foreign key and generated write inputs. A view has
+        // neither, and an `include` of it would have no CreateInput to reference.
+        this.issues.push({
+          path: `${ref.model.name}.${ref.name}`,
+          message: `"${ref.type}" is a view and cannot be the target of a relation; select from it directly instead`,
+        });
+        continue;
+      }
+      if (!tableNames.includes(ref.type)) {
         this.issues.push({
           path: `${ref.model.name}.${ref.name}`,
-          message: unknownFieldTypeMessage(ref.type, this.provider, modelNames),
+          message: unknownFieldTypeMessage(ref.type, this.provider, tableNames),
         });
         continue;
       }
 
       let foreignKey = '', localKey = '', relationName = '';
-      const nameMatch = ref.line.match(/@relation\("(\w+)"/);
-      if (nameMatch) relationName = nameMatch[1];
-      const relationMatch = ref.line.match(/@relation\((?:.*fields:\s*\[(\w+)\],)?\s*(?:.*references:\s*\[(\w+)\],?)?.*\)/);
-      if (relationMatch) {
-        foreignKey = relationMatch[1] || '';
-        localKey = relationMatch[2] || '';
+      const relationArgs = attributeArgs(ref.line, '@relation');
+      if (relationArgs) {
+        // `@relation("name", fields: [userId], references: [id])`; the name is
+        // either positional or spelled `name:`.
+        relationName = relationArgs.match(/^\s*(?:\w+\s*:\s*)?"([^"]+)"/)?.[1] ?? '';
+        foreignKey = (relationArgs.match(/\bfields\s*:\s*\[([^\]]*)\]/)?.[1] ?? '').split(',')[0]?.trim() ?? '';
+        localKey = (relationArgs.match(/\breferences\s*:\s*\[([^\]]*)\]/)?.[1] ?? '').split(',')[0]?.trim() ?? '';
       }
-      const description = ref.line.match(/@description\("(.+)"\)/)?.[1];
+      const description = unquote(attributeArgs(ref.line, '@description'));
       ref.model.relations.push({
         name: ref.name,
         type: ref.type,

package/generator/src/pull-schema.ts

@@ -0,0 +1,127 @@
+/**
+ * Pure helpers for `db:pull`.
+ *
+ * Reading SQL Server catalogs and writing schema files lives in `pull.ts`, which
+ * starts a connection as soon as it is imported. The decisions it makes about the
+ * text — which block to replace, how a view becomes a `view` block — are here so
+ * they can be tested without a database.
+ */
+import { viewSqlBody } from './dialect';
+
+/** One column as `sys.columns`/`sys.types` describe it. */
+export interface PulledColumn {
+  columnName: string;
+  dataType: string;
+  maxLength: number;
+  precision: number;
+  scale: number;
+  isNullable: boolean | number;
+}
+
+/**
+ * The schema type of an introspected SQL Server column.
+ *
+ * `max_length` is bytes, so the character types divide it by two; `-1` is `MAX`.
+ * Tables and views describe their columns the same way, so they share this.
+ */
+export function sqlServerTypeForColumn(col: PulledColumn): string {
+  let sqlType = col.dataType.toUpperCase();
+  const dt = col.dataType.toLowerCase();
+
+  if (dt === 'nvarchar' || dt === 'varchar') {
+    sqlType = col.maxLength === -1 ? `${sqlType.toUpperCase()}(MAX)` : `${sqlType.toUpperCase()}(${col.maxLength / 2})`;
+  } else if (dt === 'char' || dt === 'nchar') {
+    sqlType = `${sqlType.toUpperCase()}(${col.maxLength / 2})`;
+  } else if (dt === 'varbinary' || dt === 'binary') {
+    sqlType = col.maxLength === -1 ? `${sqlType.toUpperCase()}(MAX)` : `${sqlType.toUpperCase()}(${col.maxLength})`;
+  } else if (dt === 'decimal' || dt === 'numeric') {
+    sqlType = `${sqlType.toUpperCase()}(${col.precision}, ${col.scale})`;
+  }
+
+  return sqlType;
+}
+
+/**
+ * Where `keyword Name { ... }` starts and ends in a schema file.
+ *
+ * The closing brace is the one on its own line, not the first `}` anywhere: a
+ * view's SQL may contain one (`WHERE name <> '}'`) and a regex that stops there
+ * would truncate the block.
+ */
+export function blockRange(text: string, keyword: 'model' | 'view', name: string): { start: number; end: number } | null {
+  const header = new RegExp(`(^|\\n)[ \\t]*${keyword}\\s+${name}\\s*\\{`);
+  const match = header.exec(text);
+  if (!match) return null;
+
+  const start = match.index + (match[1]?.length ?? 0);
+  const bodyStart = match.index + match[0].length;
+  const close = /(^|\n)[ \t]*\}/.exec(text.slice(bodyStart));
+  if (!close) return null;
+
+  return { start, end: bodyStart + close.index + close[0].length };
+}
+
+/** The additional key a schema block is known by, e.g. `reporting.active_users`. */
+export function qualifiedBlockKey(name: string, schemaName: string | undefined): string {
+  return !schemaName || schemaName.toLowerCase() === 'dbo' ? name : `${schemaName}.${name}`;
+}
+
+/**
+ * A likely block name for an introspected object.
+ *
+ * `db:pull` names a new block after the table or view, dropping the plural `s`
+ * so `users` becomes `User`. A word that already ends in `s` but is singular
+ * (`status`, `address`, `analysis`) must keep it: stripping the character turns
+ * it into `Statu`, which reads like a typo in every generated client. Existing
+ * blocks keep their own name, so this only decides what a newly pulled object is
+ * called.
+ */
+export function blockNameForObject(objectName: string): string {
+  // `active_users` becomes `ActiveUser`, not `Active_user`: the block name is a
+  // generated type in every client, so it follows the schema's own casing.
+  const words = objectName.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const capitalized = (words.length > 0 ? words : [objectName])
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+  // `addresses`/`classes` lose `es`; `status`/`address`/`analysis` are singular
+  // and keep the `s`.
+  if (/sses$/i.test(capitalized)) return capitalized.slice(0, -2);
+  if (/(?:ss|us|is)$/i.test(capitalized)) return capitalized;
+  if (/s$/i.test(capitalized)) return capitalized.slice(0, -1);
+  return capitalized;
+}
+
+/**
+ * A `view` block for a catalog view.
+ *
+ * `@@sql` gets the body, not the `CREATE VIEW` statement the catalog returns:
+ * push and migrate add the `CREATE VIEW` themselves, so storing the header would
+ * produce `CREATE OR REPLACE VIEW x AS CREATE VIEW ...`.
+ */
+export function buildViewBlock(input: {
+  modelName: string;
+  viewName: string;
+  schemaName: string;
+  columns: readonly PulledColumn[];
+  definition: string | null | undefined;
+}): string | null {
+  const body = viewSqlBody(input.definition);
+  if (!body) return null;
+
+  const lines = [`view ${input.modelName} {`];
+  for (const col of input.columns) {
+    lines.push(`  ${col.columnName} ${sqlServerTypeForColumn(col)}${col.isNullable ? '?' : ''}`);
+  }
+
+  if (input.viewName !== input.modelName.toLowerCase() + 's') {
+    lines.push('', `  @@map("${input.viewName}")`);
+  }
+  if (input.schemaName && input.schemaName.toLowerCase() !== 'dbo') {
+    lines.push(`  @@schema("${input.schemaName}")`);
+  }
+
+  lines.push('', '  @@sql("""');
+  for (const line of body.split(/\r?\n/)) lines.push(`    ${line}`);
+  lines.push('  """)', '}');
+  return lines.join('\n');
+}

package/generator/src/push-apply.ts

@@ -8,8 +8,17 @@
  * The database is two functions rather than the adapter, which keeps this testable
  * and keeps the driver out of the decision making.
  */
-import { PushDialect } from './dialect';
-import { PushIndex, PushModel, directiveName, qualifiedTableName, safeIdentifierName } from './push-schema';
+import { PushDialect, normalizeViewSql } from './dialect';
+import {
+  PushIndex,
+  PushModel,
+  PushView,
+  directiveName,
+  qualifiedTableName,
+  qualifiedViewName,
+  safeIdentifierName,
+} from './push-schema';
+import { orderViewsByDependency } from './view-order';
 
 /** The two things this needs from a database connection. */
 export interface PushDatabase {
@@ -28,6 +37,8 @@ export interface ApplyResult {
   columnsAdded: number;
   indexesCreated: number;
   uniqueConstraintsAdded: number;
+  /** How many views were created or replaced. */
+  viewsApplied: number;
 }
 
 /**
@@ -41,6 +52,7 @@ export async function applySchema(
   models: readonly PushModel[],
   dialect: PushDialect,
   db: PushDatabase,
+  views: readonly PushView[] = [],
 ): Promise<ApplyResult> {
   const result: ApplyResult = {
     tablesCreated: 0,
@@ -48,6 +60,7 @@ export async function applySchema(
     columnsAdded: 0,
     indexesCreated: 0,
     uniqueConstraintsAdded: 0,
+    viewsApplied: 0,
   };
 
   for (const model of models) {
@@ -89,7 +102,9 @@ export async function applySchema(
         // A new `@unique` column needs its unique too, and on SQLite that cannot
         // ride along with the ADD COLUMN — SQLite refuses to add a UNIQUE column.
         if (field.isUnique && !field.isId && !dialect.supportsUniqueInlineOnAddColumn) {
-          const indexName = `UQ_${safeName}_${field.name}`;
+          // The same name `db:migrate` expects for this column's unique, so the
+          // next diff sees push's artifact instead of adding another one.
+          const indexName = field.uniqueName ?? `UQ_${safeName}_${field.name}`;
           const quoted = dialect.quote(indexName);
           if ((await db.query(dialect.uniqueConstraintExists(tableName, indexName))).length === 0) {
             db.log(`Creating unique index ${quoted} on table ${sqlTableName}...`);
@@ -112,7 +127,6 @@ export async function applySchema(
         db.log(`Creating unique index ${quoted} on table ${sqlTableName}...`);
         await db.execute(dialect.createUniqueIndex(quoted, sqlTableName, quoteFields(entry.fields)));
         result.indexesCreated += 1;
-        result.uniqueConstraintsAdded += 1;
       }
       result.uniqueConstraintsAdded += 1;
     }
@@ -122,11 +136,54 @@ export async function applySchema(
       if ((await db.query(dialect.indexExists(tableName, name))).length > 0) continue;
       const quoted = dialect.quote(name);
       db.log(`Creating index ${quoted} on table ${sqlTableName}...`);
-      await db.execute(dialect.createIndex(quoted, sqlTableName, quoteFields(directive.fields)));
+      await db.execute(
+        dialect.createIndex(quoted, sqlTableName, quoteFields(directive.fields), {
+          includeFields: directive.includeFields ? quoteFields(directive.includeFields) : undefined,
+          filter: directive.filter,
+          options: directive.options,
+        }),
+      );
       result.indexesCreated += 1;
     }
   }
 
+  // Views are applied after every table: a view may select from a table this same
+  // push created, and SQL Server validates the reference while compiling it.
+  // Within the views, a dependent view has to come after the one it reads.
+  const orderedViews = orderViewsByDependency(
+    views.map((view) => ({
+      view,
+      names: [qualifiedViewName(view), view.viewName],
+      sql: view.sql,
+    })),
+  );
+  if (orderedViews.cyclic) {
+    // The definitions cannot all exist at once; the database reports which one
+    // is missing, which is more useful than a generic ordering error here.
+    db.log('Warning: view definitions reference each other in a cycle; keeping schema order.');
+  }
+
+  for (const { view } of orderedViews.ordered) {
+    const viewName = qualifiedViewName(view);
+    const sqlViewName = dialect.quoteTable(viewName);
+    db.log(`Processing view ${sqlViewName}...`);
+
+    const rows = await db.query(dialect.viewDefinition(viewName));
+    const existing = rows[0] as { definition?: string | null } | undefined;
+    if (existing && normalizeViewSql(existing.definition) === normalizeViewSql(view.sql)) {
+      // The catalog and the schema agree; recreating would just churn dependencies.
+      continue;
+    }
+
+    if (existing && !dialect.supportsCreateOrReplaceView) {
+      db.log(`Dropping view ${sqlViewName} before recreating it...`);
+      await db.execute(dialect.dropView(sqlViewName));
+    }
+    db.log(`Creating view ${sqlViewName}...`);
+    await db.execute(dialect.createView(sqlViewName, view.sql));
+    result.viewsApplied += 1;
+  }
+
   return result;
 }