@an5/orm 1.0.8 → 1.1.0

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

@@ -0,0 +1,17 @@
+/**
+ * "Did you mean" for typos.
+ *
+ * Lives on its own because two callers need it and neither should own it:
+ * the config loader (a mistyped option key) and the field type registry (a
+ * type written for the wrong database). Both want the nearest candidate out
+ * of a known list, or nothing at all when the input is not close enough that
+ * a suggestion would be honest.
+ */
+/** Levenshtein distance between two strings. */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The candidate closest to `input`, or null when none is close enough to be a
+ * plausible typo. Comparing case-insensitively keeps `nvarchar` from suggesting
+ * something unrelated just because of capitalisation.
+ */
+export declare function suggest(input: string, candidates: readonly string[]): string | null;

package/dist/generator/src/suggest.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * "Did you mean" for typos.
+ *
+ * Lives on its own because two callers need it and neither should own it:
+ * the config loader (a mistyped option key) and the field type registry (a
+ * type written for the wrong database). Both want the nearest candidate out
+ * of a known list, or nothing at all when the input is not close enough that
+ * a suggestion would be honest.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editDistance = editDistance;
+exports.suggest = suggest;
+/** Levenshtein distance between two strings. */
+function editDistance(a, b) {
+    const rows = [];
+    for (let i = 0; i <= a.length; i++)
+        rows.push([i, ...new Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        rows[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+        }
+    }
+    return rows[a.length][b.length];
+}
+/**
+ * The candidate closest to `input`, or null when none is close enough to be a
+ * plausible typo. Comparing case-insensitively keeps `nvarchar` from suggesting
+ * something unrelated just because of capitalisation.
+ */
+function suggest(input, candidates) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const candidate of candidates) {
+        const distance = editDistance(input.toLowerCase(), candidate.toLowerCase());
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return best !== null && bestDistance <= Math.max(2, Math.floor(input.length / 3)) ? best : null;
+}

package/dist/generator/src/type-kinds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a field *is*, for the generators that need a real type.
+ *
+ * The parser gives every generator the same TypeScript type, and that type loses
+ * what a language needs: `INT`, `FLOAT` and `DECIMAL` all arrive as `number`, so
+ * the Go client generated every numeric column as a `string`, and the Python, Rust
+ * and .NET clients turned a `DECIMAL` into an integer type. The declared type is
+ * right there in `Field.sqlType`, so it decides — with the TypeScript type as the
+ * fallback for metadata generated before that was recorded.
+ */
+import { Provider } from './field-types';
+/** The categories a generated language type can be built from. */
+export type FieldKind = 'int' | 'bigint' | 'float' | 'bool' | 'date' | 'bytes' | 'json' | 'vector' | 'string';
+export interface KindInput {
+    /** The TypeScript type the parser produced, e.g. `number | bigint`. */
+    type: string;
+    /** The type as written in the schema, e.g. `DECIMAL(10,2)`. */
+    sqlType?: string | undefined;
+}
+/**
+ * The category a field belongs to.
+ *
+ * `TIMESTAMP` is the reason `provider` is a parameter: it is a rowversion on SQL
+ * Server and a point in time everywhere else, and the same word has to produce
+ * bytes in one and a date in the other.
+ */
+export declare function fieldKind(field: KindInput, provider?: Provider | undefined): FieldKind;

package/dist/generator/src/type-kinds.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fieldKind = fieldKind;
+const INT = ['INT', 'INTEGER', 'SMALLINT', 'TINYINT', 'MEDIUMINT', 'INT2', 'INT4', 'SERIAL', 'SMALLSERIAL', 'YEAR'];
+const BIGINT = ['BIGINT', 'INT8', 'BIGSERIAL', 'UNSIGNED BIG INT'];
+const FLOAT = ['FLOAT', 'REAL', 'DOUBLE', 'DOUBLE PRECISION', 'DECIMAL', 'NUMERIC', 'MONEY', 'SMALLMONEY', 'FIXED'];
+const BOOL = ['BIT', 'BOOL', 'BOOLEAN'];
+const DATE = [
+    'DATE', 'DATETIME', 'DATETIME2', 'SMALLDATETIME', 'DATETIMEOFFSET',
+    'TIME', 'TIMETZ', 'TIMESTAMPTZ', 'TIME WITH TIME ZONE', 'TIME WITHOUT TIME ZONE',
+    'TIMESTAMP WITH TIME ZONE', 'TIMESTAMP WITHOUT TIME ZONE',
+];
+const BYTES = ['BINARY', 'VARBINARY', 'IMAGE', 'BLOB', 'TINYBLOB', 'MEDIUMBLOB', 'LONGBLOB', 'BYTEA', 'ROWVERSION', 'BYTES'];
+const JSON = ['JSON', 'JSONB', 'SQL_VARIANT'];
+/** `DECIMAL(10,2)` → `DECIMAL`. */
+function declaredBase(sqlType) {
+    const withoutParams = sqlType.replace(/\([^)]*\)/g, ' ').trim();
+    return withoutParams.replace(/\s+/g, ' ').toUpperCase();
+}
+/**
+ * The category a field belongs to.
+ *
+ * `TIMESTAMP` is the reason `provider` is a parameter: it is a rowversion on SQL
+ * Server and a point in time everywhere else, and the same word has to produce
+ * bytes in one and a date in the other.
+ */
+function fieldKind(field, provider) {
+    const base = field.sqlType ? declaredBase(field.sqlType) : '';
+    if (base) {
+        if (base === 'TIMESTAMP')
+            return provider === 'mssql' ? 'bytes' : 'date';
+        if (INT.includes(base))
+            return 'int';
+        if (BIGINT.includes(base))
+            return 'bigint';
+        if (FLOAT.includes(base))
+            return 'float';
+        if (BOOL.includes(base))
+            return 'bool';
+        if (DATE.includes(base) || base === 'TIMESTAMP')
+            return 'date';
+        if (BYTES.includes(base))
+            return 'bytes';
+        if (JSON.includes(base))
+            return 'json';
+        if (base === 'VECTOR')
+            return 'vector';
+        return 'string';
+    }
+    // No declared type: fall back to what the TypeScript type can still tell us. A
+    // plain `number` is an integer here, which is what every generator assumed
+    // before `sqlType` was available.
+    const raw = field.type.trim().toLowerCase();
+    // Checked before the brackets are stripped, or `number[] | string` — the vector
+    // type — would read as a number.
+    if (raw.includes('[]'))
+        return 'vector';
+    const ts = raw.replace(/[?\]]/g, '').trim();
+    if (ts.startsWith('number | bigint'))
+        return 'bigint';
+    if (ts.startsWith('number'))
+        return 'int';
+    if (ts.startsWith('date'))
+        return 'date';
+    if (ts.startsWith('bool'))
+        return 'bool';
+    if (ts.startsWith('buffer'))
+        return 'bytes';
+    if (ts === 'any')
+        return 'json';
+    return 'string';
+}

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

@@ -1,27 +1,60 @@
-export interface Field {
-    name: string;
-    type: string;
-    sqlType: string;
-    isOptional: boolean;
-    hasDefault: boolean;
-    isId: boolean;
-    description?: string;
-}
-export interface Relation {
-    name: string;
-    type: string;
-    isArray: boolean;
-    isOptional: boolean;
-    foreignKey: string;
-    localKey: string;
-    relationName: string;
-}
-export interface Model {
-    name: string;
-    tableName: string;
-    schemaName: string;
-    fields: Field[];
-    relations: Relation[];
-    compoundUniques?: string[][];
-    description?: string;
-}
+import { Provider } from './field-types';
+export interface Field {
+    name: string;
+    type: string;
+    sqlType: string;
+    isOptional: boolean;
+    hasDefault: boolean;
+    isId: boolean;
+    description?: string;
+}
+export interface Relation {
+    name: string;
+    type: string;
+    isArray: boolean;
+    isOptional: boolean;
+    foreignKey: string;
+    localKey: string;
+    relationName: string;
+    /** From a trailing @description("...") on the relation line. */
+    description?: string;
+}
+export interface Model {
+    name: string;
+    tableName: string;
+    /** Empty for a database with no schemas, or when `@@schema("")` says so. */
+    schemaName: string;
+    /**
+     * The database this schema targets. Set by `SchemaParser`, and what decides how a
+     * table name is written — see `bracketedTableName`.
+     */
+    provider?: Provider | undefined;
+    fields: Field[];
+    relations: Relation[];
+    compoundUniques?: string[][];
+    description?: string;
+}
+/**
+ * The table name as it goes into the generated metadata.
+ *
+ * SQL Server keeps the bracketed form it has always had. Every other provider gets
+ * the bare name, with the schema as a plain prefix, because the brackets are not
+ * portable: `[dbo].[users]` is invalid SQL in PostgreSQL, and on SQLite it fails with
+ * "no such table: dbo.users" — which is why the adapters had to strip it afterwards.
+ * A bare name is correct everywhere once the adapter quotes it, and the adapters
+ * already quote per dialect (`quote()` in `@an5/adapters`, `An5DbContext.Quote()` in
+ * the .NET client), so the one form that needs no translation is the one emitted.
+ *
+ * `dbo` is SQL Server's default schema and only SQL Server's: with `@@schema("")` —
+ * an empty schema, meant for databases that have no schema concept — the prefix has
+ * to go, because `[].[users]` is not valid SQL. The `[${schemaName}].[${tableName}]`
+ * formula used to be written out in six places, so every dialect got `[dbo]`.
+ */
+export declare function bracketedTableName(model: Model): string;
+/**
+ * The table name as `schema.table`, for clients that pass a string instead of SQL.
+ *
+ * Unquoted for the same reason as `bracketedTableName`: these strings go to the same
+ * per-dialect quoting.
+ */
+export declare function dottedTableName(model: Model): string;

package/dist/generator/src/types.js

@@ -1,2 +1,41 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bracketedTableName = bracketedTableName;
+exports.dottedTableName = dottedTableName;
+/**
+ * The table name as it goes into the generated metadata.
+ *
+ * SQL Server keeps the bracketed form it has always had. Every other provider gets
+ * the bare name, with the schema as a plain prefix, because the brackets are not
+ * portable: `[dbo].[users]` is invalid SQL in PostgreSQL, and on SQLite it fails with
+ * "no such table: dbo.users" — which is why the adapters had to strip it afterwards.
+ * A bare name is correct everywhere once the adapter quotes it, and the adapters
+ * already quote per dialect (`quote()` in `@an5/adapters`, `An5DbContext.Quote()` in
+ * the .NET client), so the one form that needs no translation is the one emitted.
+ *
+ * `dbo` is SQL Server's default schema and only SQL Server's: with `@@schema("")` —
+ * an empty schema, meant for databases that have no schema concept — the prefix has
+ * to go, because `[].[users]` is not valid SQL. The `[${schemaName}].[${tableName}]`
+ * formula used to be written out in six places, so every dialect got `[dbo]`.
+ */
+function bracketedTableName(model) {
+    const qualified = model.schemaName
+        ? `${model.schemaName}.${model.tableName}`
+        : model.tableName;
+    if ((model.provider ?? 'mssql') !== 'mssql')
+        return qualified;
+    return model.schemaName
+        ? `[${model.schemaName}].[${model.tableName}]`
+        : `[${model.tableName}]`;
+}
+/**
+ * The table name as `schema.table`, for clients that pass a string instead of SQL.
+ *
+ * Unquoted for the same reason as `bracketedTableName`: these strings go to the same
+ * per-dialect quoting.
+ */
+function dottedTableName(model) {
+    return model.schemaName
+        ? `${model.schemaName}.${model.tableName}`
+        : model.tableName;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { An5ORM, an5Orm, default } from "./an5Orm";
-export type { Middleware, MiddlewareParams } from "./an5Orm";
 export { An5ClientKnownRequestError } from "./errors";
 export { DEFAULT_METADATA } from "./metadata";
 export type { RelationDef, ModelFieldMeta, An5Metadata } from "./metadata";
+export { quoteIdentifier, quoteTableIdentifier, sanitizeParamName, normalizeSortDirection, toNonNegativeInt, buildOrderBy, parseWhere, } from "./sql-utils";
+export { generateDiff, buildMigrationFile, buildCreateTableSql, generateColumnDiff, parseSchemaText, } from "./migration-core";
+export { An5Adapter, createAn5Adapter, AdapterTableClient, } from "@an5/adapters";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,15 +1,26 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_METADATA = exports.An5ClientKnownRequestError = exports.default = exports.an5Orm = exports.An5ORM = void 0;
-var an5Orm_1 = require("./an5Orm");
-Object.defineProperty(exports, "An5ORM", { enumerable: true, get: function () { return an5Orm_1.An5ORM; } });
-Object.defineProperty(exports, "an5Orm", { enumerable: true, get: function () { return an5Orm_1.an5Orm; } });
-Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(an5Orm_1).default; } });
+exports.AdapterTableClient = exports.createAn5Adapter = exports.An5Adapter = exports.parseSchemaText = exports.generateColumnDiff = exports.buildCreateTableSql = exports.buildMigrationFile = exports.generateDiff = exports.parseWhere = exports.buildOrderBy = exports.toNonNegativeInt = exports.normalizeSortDirection = exports.sanitizeParamName = exports.quoteTableIdentifier = exports.quoteIdentifier = exports.DEFAULT_METADATA = exports.An5ClientKnownRequestError = void 0;
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "An5ClientKnownRequestError", { enumerable: true, get: function () { return errors_1.An5ClientKnownRequestError; } });
 var metadata_1 = require("./metadata");
 Object.defineProperty(exports, "DEFAULT_METADATA", { enumerable: true, get: function () { return metadata_1.DEFAULT_METADATA; } });
+var sql_utils_1 = require("./sql-utils");
+Object.defineProperty(exports, "quoteIdentifier", { enumerable: true, get: function () { return sql_utils_1.quoteIdentifier; } });
+Object.defineProperty(exports, "quoteTableIdentifier", { enumerable: true, get: function () { return sql_utils_1.quoteTableIdentifier; } });
+Object.defineProperty(exports, "sanitizeParamName", { enumerable: true, get: function () { return sql_utils_1.sanitizeParamName; } });
+Object.defineProperty(exports, "normalizeSortDirection", { enumerable: true, get: function () { return sql_utils_1.normalizeSortDirection; } });
+Object.defineProperty(exports, "toNonNegativeInt", { enumerable: true, get: function () { return sql_utils_1.toNonNegativeInt; } });
+Object.defineProperty(exports, "buildOrderBy", { enumerable: true, get: function () { return sql_utils_1.buildOrderBy; } });
+Object.defineProperty(exports, "parseWhere", { enumerable: true, get: function () { return sql_utils_1.parseWhere; } });
+var migration_core_1 = require("./migration-core");
+Object.defineProperty(exports, "generateDiff", { enumerable: true, get: function () { return migration_core_1.generateDiff; } });
+Object.defineProperty(exports, "buildMigrationFile", { enumerable: true, get: function () { return migration_core_1.buildMigrationFile; } });
+Object.defineProperty(exports, "buildCreateTableSql", { enumerable: true, get: function () { return migration_core_1.buildCreateTableSql; } });
+Object.defineProperty(exports, "generateColumnDiff", { enumerable: true, get: function () { return migration_core_1.generateColumnDiff; } });
+Object.defineProperty(exports, "parseSchemaText", { enumerable: true, get: function () { return migration_core_1.parseSchemaText; } });
+var adapters_1 = require("@an5/adapters");
+Object.defineProperty(exports, "An5Adapter", { enumerable: true, get: function () { return adapters_1.An5Adapter; } });
+Object.defineProperty(exports, "createAn5Adapter", { enumerable: true, get: function () { return adapters_1.createAn5Adapter; } });
+Object.defineProperty(exports, "AdapterTableClient", { enumerable: true, get: function () { return adapters_1.AdapterTableClient; } });
 //# sourceMappingURL=index.js.map

package/dist/logger.js

@@ -84,7 +84,7 @@ class Logger {
         this.log('warn', message, options);
     }
     error(message, error, options) {
-        this.log('error', message, { ...options, error });
+        this.log('error', message, { ...options, ...(error !== undefined ? { error } : {}) });
     }
     child(context) {
         return new Logger({

package/dist/migration-core.d.ts

@@ -0,0 +1,102 @@
+import { Provider } from './generator/src/field-types';
+export interface SchemaField {
+    name: string;
+    sqlType: string;
+    isOptional: boolean;
+    isId: boolean;
+    isUnique: boolean;
+    uniqueName?: string | undefined;
+    defaultValue?: string | undefined;
+}
+export interface SchemaIndexDefinition {
+    fields: string[];
+    name?: string;
+    includeFields?: string[];
+    filter?: string;
+    options?: string;
+}
+export interface SchemaModel {
+    name: string;
+    /**
+     * The table to create, schema-qualified when the model named a schema other than
+     * `dbo`. `dbo` stays implicit so an unqualified model produces the same SQL it
+     * always has.
+     */
+    tableName: string;
+    fields: SchemaField[];
+    compoundUniques: Array<string[] | SchemaIndexDefinition>;
+    indexes: Array<string[] | SchemaIndexDefinition>;
+}
+export interface DbColumn {
+    columnName: string;
+    dataType: string;
+    maxLength?: number;
+    precision?: number;
+    scale?: number;
+    isNullable: boolean;
+    isPrimaryKey: boolean;
+    isIdentity: boolean;
+    defaultValue?: string;
+}
+export interface MigrationOp {
+    type: 'CREATE_TABLE' | 'ADD_COLUMN' | 'DROP_COLUMN' | 'ALTER_COLUMN' | 'ADD_INDEX' | 'ADD_UNIQUE' | 'DROP_INDEX' | 'DROP_UNIQUE' | 'DROP_TABLE';
+    table: string;
+    column?: string;
+    details?: string;
+    sql?: string;
+    previousSqlType?: string;
+    previousNullable?: boolean;
+    riskWarnings?: string[];
+    preflightSql?: string[];
+}
+export interface TableArtifacts {
+    indexes?: string[];
+    uniqueConstraints?: string[];
+}
+export interface MigrationSections {
+    preflight: string;
+    up: string;
+    down: string;
+    hasDown: boolean;
+}
+export interface AppliedMigrationRef {
+    id: string;
+}
+export interface MigrationCommandOptions {
+    dryRun: boolean;
+    rest: string[];
+}
+export declare function parseSqlType(raw: string): string;
+export declare function formatDbColumnSqlType(column: DbColumn): string;
+export declare function mapDefault(val: string): string;
+export declare function safeIdentifierName(raw: string): string;
+export declare function quoteTableName(raw: string): string;
+export declare function tableIdentityName(raw: string): string;
+export declare function buildAlterColumnWarnings(previousSqlType: string, nextSqlType: string, previousNullable: boolean, nextNullable: boolean): string[];
+export declare function buildAlterColumnPreflightSql(tableName: string, columnName: string, previousSqlType: string, nextSqlType: string, previousNullable: boolean, nextNullable: boolean): string[];
+export declare function buildAddColumnPreflightSql(tableName: string, field: SchemaField): string[];
+export declare function buildUniqueConstraintPreflightSql(tableName: string, fields: string[]): string[];
+/**
+ * Reads a `.an5` schema into models to compare against the database.
+ *
+ * `provider` decides what counts as a column and what counts as a relation; it
+ * defaults to SQL Server. A type the provider does not have is reported rather
+ * than skipped — skipping it means the migration silently never mentions that
+ * column. A token matching a model in the schema is a relation, so that
+ * comparison waits until the whole schema has been read.
+ */
+export declare function parseSchemaText(text: string, provider?: Provider): SchemaModel[];
+export declare function buildCreateTableSql(model: SchemaModel): string;
+export declare function buildIndexDiff(model: SchemaModel, artifacts: TableArtifacts, ops: MigrationOp[]): void;
+export declare function generateColumnDiff(model: SchemaModel, dbColumns: DbColumn[], ops: MigrationOp[]): void;
+export declare function generateDiff(schemaModels: SchemaModel[], dbTables: string[], introspectTable: (tableName: string) => Promise<DbColumn[]>, introspectArtifacts?: (tableName: string) => Promise<TableArtifacts>): Promise<MigrationOp[]>;
+export declare function buildMigrationFile(timestamp: string, ops: MigrationOp[]): string;
+export declare function buildDownMigrationSql(ops: MigrationOp[]): string;
+export declare function parseMigrationSections(sql: string): MigrationSections;
+export declare function splitSqlBatches(sql: string): string[];
+export declare function parseRollbackSelection(args: string[], applied: AppliedMigrationRef[]): {
+    count: number;
+    label: string;
+};
+export declare function parseMigrationCommandOptions(args: string[]): MigrationCommandOptions;
+//# sourceMappingURL=migration-core.d.ts.map