uql-orm 0.21.0 → 0.22.0

package/dist/type/config.d.ts

@@ -1,6 +1,5 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { ForeignKeyAction } from '../schema/types.js';
-import type { NamingStrategy } from './namingStrategy.js';
 import type { Querier } from './querier.js';
 import type { QuerierPool } from './querierPool.js';
 import type { Type } from './utility.js';
@@ -29,11 +28,6 @@ export interface Config {
      * @default 'uql_migrations'
      */
     tableName?: string;
-    /**
-     * The naming strategy for mapping class/property names to database table/column names.
-     * @default DefaultNamingStrategy (camelCase -> camelCase)
-     */
-    namingStrategy?: NamingStrategy;
     /**
      * Default action for foreign key ON DELETE and ON UPDATE clauses.
      * @default 'NO ACTION'

package/dist/type/dialect.d.ts

@@ -74,11 +74,11 @@ export interface EngineFeatures {
     /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
     readonly columnComment: boolean;
     /**
-     * How vector indexes are emitted: inline in CREATE TABLE (MySQL/MariaDB), a standalone
-     * `CREATE INDEX ... USING <type> (col opclass)` (Postgres/SQLite), or a standalone
-     * `CREATE VECTOR INDEX (col opclass)` with no access-method keyword (CockroachDB's native type).
+     * Whether a vector index is declared inline in `CREATE TABLE` (MySQL/MariaDB) rather than as its own
+     * `CREATE INDEX` statement. The statement's shape itself is the dialect's business, see
+     * `AbstractSqlDialect.getCreateIndexStatement`.
      */
-    readonly vectorIndexStyle: 'inline' | 'create' | 'native';
+    readonly inlineVectorIndex: boolean;
     /** Whether the dialect requires/allows (n) length constraints on vector types. */
     readonly vectorSupportsLength: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
@@ -196,3 +196,11 @@ export interface SqlQueryDialect extends QueryDialect {
      */
     placeholder(index: number): string;
 }
+/**
+ * An index capability that some engines have and others reject outright. Verified live: expression
+ * indexes exist everywhere but MariaDB 12.3 (which needs a generated column); prefix lengths are
+ * MySQL-family only and *required* there to index `TEXT`; `NULLS FIRST/LAST` and operator classes are
+ * Postgres-only (CockroachDB 26.2 answers "unimplemented"); `INCLUDE` is Postgres-wire only.
+ */
+export type IndexFeature = 'expression' | 'prefixLength' | 'nullsOrder' | 'opsClass' | 'include';
+export declare const INDEX_FEATURE_LABELS: Record<IndexFeature, string>;

package/dist/type/dialect.js

@@ -1 +1,7 @@
-export {};
+export const INDEX_FEATURE_LABELS = {
+    expression: 'expression indexes',
+    prefixLength: 'index prefix lengths',
+    nullsOrder: 'NULLS FIRST/LAST in an index',
+    opsClass: 'index operator classes',
+    include: 'covering indexes (INCLUDE)',
+};

package/dist/type/entity.d.ts

@@ -1,7 +1,7 @@
 import type { IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
-import type { Json, Scalar, Type, Unpacked } from './utility.js';
+import type { DistributiveOmit, Json, Scalar, Type, Unpacked } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /**
  * Allow to customize the name of the property that identifies an entity
@@ -344,17 +344,66 @@ export type IndexTypeOptions = {
     distance?: never;
 };
 /**
- * Index metadata from @Index decorator.
+ * One entry of an index: a column name by default, `raw(...)` to index an expression, or an object
+ * when the entry needs more than a name.
+ *
+ * @example
+ * ```ts
+ * @Index(['tenantId', { column: 'createdAt', order: 'desc' }])   // keyset pagination
+ * @Index([raw('lower("email")')], { unique: true })              // case-insensitive uniqueness
+ * @Index([{ column: 'body', length: 64 }])                       // MySQL needs a prefix on TEXT
+ * @Index(['data'], { type: 'gin' })                              // JSONB containment
+ * ```
+ */
+export type IndexColumnInput = string | QueryRaw | IndexColumnOptions;
+/**
+ * What an index entry can carry besides the thing being indexed. Shared with the normalized
+ * `IndexColumnSchema`, so the authored and internal shapes cannot drift apart.
+ */
+export type IndexColumnModifiers = {
+    /**
+     * Index only the first `n` characters. MySQL and MariaDB *require* this to index a `TEXT`/`BLOB`
+     * column at all ("used in key specification without a key length"); no other engine accepts it.
+     */
+    readonly length?: number;
+    /** Stored sort order, which lets `ORDER BY ... DESC` pagination use the index. */
+    readonly order?: 'asc' | 'desc';
+    /** Where NULLs sort. Postgres only. */
+    readonly nulls?: 'first' | 'last';
+    /** Operator class, e.g. `jsonb_path_ops` for a smaller GIN index. Postgres only. */
+    readonly opsClass?: string;
+};
+export type IndexColumnOptions = IndexColumnModifiers & {
+    /** The column to index, or `raw(...)` for an expression. */
+    readonly column: string | QueryRaw;
+};
+/**
+ * One index entry, normalized: {@link IndexColumnInput}'s three authored shapes all reduce to this
+ * before any dialect or generator sees them, so rendering never re-parses the sugar.
+ */
+export type IndexColumnSchema = IndexColumnModifiers & {
+    /** A column name, or raw SQL when {@link expression} is set. */
+    readonly column: string;
+    /** Whether {@link column} is an expression to emit as-is rather than an identifier to quote. */
+    readonly expression?: boolean;
+};
+/**
+ * An index as stored in entity metadata: authored options with the columns normalized.
  */
 export type EntityIndexMeta = {
-    /** Column names in the index */
-    columns: string[];
+    /** The indexed columns, in order. */
+    columns: readonly IndexColumnSchema[];
     /** Custom index name */
     name?: string;
     /** Whether index is unique; omit or `false` for a non-unique index (default). */
     unique?: boolean;
     /** Partial index condition (WHERE clause) */
     where?: string;
+    /**
+     * Extra columns stored in the index but not part of its key, so a query reading only these is
+     * answered from the index alone. Postgres-wire only (`INCLUDE`).
+     */
+    include?: readonly string[];
 } & VectorIndexOptions & IndexTypeOptions;
 export type EntityMeta<E> = {
     readonly entity: Type<E>;
@@ -392,8 +441,20 @@ export type EntityOptions<E = unknown> = {
     /** Scalar fields; use `isId: true` on exactly one field for the primary key. */
     readonly fields?: Record<string, FieldOptions>;
     readonly relations?: Record<string, RelationOptions>;
-    readonly indexes?: readonly EntityIndexMeta[];
+    readonly indexes?: readonly EntityIndexInput[];
     /** Map hook events to method names on the entity class. */
     readonly hooks?: Partial<Record<HookEvent, readonly string[]>>;
 };
+/**
+ * Everything an index carries beyond its columns, shared by `@Index`, `defineEntity` and the
+ * migration builder's `table.index(...)`. `DistributiveOmit` (not plain `Omit`) keeps `type`/
+ * `distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
+ */
+export type IndexOptions = DistributiveOmit<EntityIndexMeta, 'columns'>;
+/**
+ * An index as authored, before {@link appendEntityIndex} normalizes its columns.
+ */
+export type EntityIndexInput = IndexOptions & {
+    readonly columns: readonly IndexColumnInput[];
+};
 export {};

package/dist/type/migration.d.ts

@@ -1,7 +1,8 @@
+import type { VectorCast } from '../dialect/vectorCast.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from '../migrate/builder/types.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
-import type { EntityMeta, FieldOptions, LoggingOptions, NamingStrategy, SqlQuerier, Type, VectorIndexOptions } from './index.js';
+import type { EntityMeta, FieldOptions, IndexColumnSchema, LoggingOptions, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
  * Defines a migration using a simple object literal
  */
@@ -72,10 +73,6 @@ export interface MigratorOptions {
      * Entities to use for schema generation
      */
     readonly entities?: Type<unknown>[];
-    /**
-     * Naming strategy for database tables and columns
-     */
-    readonly namingStrategy?: NamingStrategy;
     /**
      * Default action for foreign key ON DELETE and ON UPDATE clauses.
      */
@@ -101,6 +98,13 @@ export interface MigrationResult {
  */
 export interface ColumnSchema {
     readonly name: string;
+    /**
+     * The engine's own type spelling, as introspection read it (`tinyint(1)`, `DATETIME`, `VARCHAR`).
+     * Deliberately not a {@link CanonicalType}: the diff has to compare what the engine would *store*,
+     * and several canonical types share one storage type per engine - an entity `boolean` is `TINYINT(1)`
+     * on MySQL and `INTEGER` on SQLite. Comparing canonical categories instead reports an alteration on
+     * every sync for those columns. Use `sqlToCanonical` to interpret it.
+     */
     readonly type: string;
     readonly nullable: boolean;
     readonly defaultValue?: unknown;
@@ -127,10 +131,20 @@ export interface TableSchema {
  */
 export interface IndexSchema extends VectorIndexOptions {
     readonly name: string;
-    readonly columns: string[];
+    readonly columns: readonly IndexColumnSchema[];
     readonly unique: boolean;
     /** Index type (btree, hnsw, ivfflat, etc.) */
     readonly type?: IndexType;
+    /** Partial index condition (WHERE clause) */
+    readonly where?: string;
+    /** Non-key columns stored in the index (Postgres-wire `INCLUDE`). */
+    readonly include?: readonly string[];
+    /**
+     * The indexed column's vector type, which pgvector's operator-class names are built from
+     * (`halfvec_cosine_ops`). Absent for a non-vector index, and for an index whose column types are
+     * unknown, where `vector` is assumed.
+     */
+    readonly vectorType?: VectorCast;
 }
 /**
  * Represents a foreign key constraint
@@ -171,10 +185,11 @@ export interface SchemaGenerator {
     generateCreateTable<E>(entity: Type<E>, options?: {
         ifNotExists?: boolean;
     }): string[];
-    /**
-     * Generate DROP TABLE statement for an entity
-     */
-    generateDropTable<E>(entity: Type<E>): string;
+    /** Generate DROP TABLE statement. */
+    generateDropTable(tableName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
     /**
      * Generate ALTER TABLE statements based on schema diff
      */
@@ -215,21 +230,19 @@ export interface SchemaGenerator {
     generateCreateIndexFromNode(index: IndexNode, options?: {
         ifNotExists?: boolean;
     }): string;
-    /** Generate DROP TABLE statement from a TableNode */
-    generateDropTableFromNode(table: TableNode, options?: {
-        ifExists?: boolean;
-    }): string;
     /** DDL from a `TableDefinition`, one string per `querier.run`. */
     generateCreateTableFromDefinition(table: TableDefinition, options?: {
         ifNotExists?: boolean;
     }): string[];
-    /** Generate DROP TABLE statement */
-    generateDropTableSql(tableName: string, options?: {
-        ifExists?: boolean;
-        cascade?: boolean;
-    }): string;
     /** Generate RENAME TABLE statement */
     generateRenameTableSql(oldName: string, newName: string): string;
+}
+/**
+ * The column and constraint DDL a migration builder emits, which only a SQL engine has. Split from
+ * {@link SchemaGenerator} because MongoDB used to satisfy these six by returning `''`: a document store
+ * has no `ADD COLUMN`, and an empty statement silently did nothing rather than saying so.
+ */
+export interface SqlDdlGenerator extends SchemaGenerator {
     /** Generate ADD COLUMN statement */
     generateAddColumnSql(tableName: string, column: FullColumnDefinition): string;
     /** Generate ALTER COLUMN statement */
@@ -238,10 +251,6 @@ export interface SchemaGenerator {
     generateDropColumnSql(tableName: string, columnName: string): string;
     /** Generate RENAME COLUMN statement */
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
-    /** Generate CREATE INDEX statement from IndexSchema */
-    generateCreateIndexSql(tableName: string, index: IndexSchema): string;
-    /** Generate DROP INDEX statement */
-    generateDropIndexSql(tableName: string, indexName: string): string;
     /** Generate ADD FOREIGN KEY statement */
     generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
     /** Generate DROP FOREIGN KEY statement */

package/dist/type/vector.d.ts

@@ -5,9 +5,12 @@ import type { IndexType } from '../schema/types.js';
  * - `l2` - Euclidean distance
  * - `inner` - inner (dot) product
  * - `l1` - Manhattan distance
- * - `hamming` - for binary vectors
+ *
+ * @remarks Hamming distance is absent because no engine can express it over a float vector column:
+ * pgvector's `<~>`/`bit_hamming_ops` and sqlite-vec's `vec_distance_hamming` both require a *bit*
+ * vector, which no field type maps to. It would be a value that compiles and always throws.
  */
-export type VectorDistance = 'cosine' | 'l2' | 'inner' | 'l1' | 'hamming';
+export type VectorDistance = 'cosine' | 'l2' | 'inner' | 'l1';
 /**
  * Vector similarity search options - used inside `$sort` on vector fields.
  *

package/dist/util/index.d.ts

@@ -2,6 +2,7 @@ export * from './dialect.util.js';
 export * from './field.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
+export * from './indexColumn.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';

package/dist/util/index.js

@@ -2,6 +2,7 @@ export * from './dialect.util.js';
 export * from './field.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
+export * from './indexColumn.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';

package/dist/util/indexColumn.util.d.ts

@@ -0,0 +1,6 @@
+import { type IndexColumnInput, type IndexColumnSchema } from '../type/index.js';
+/**
+ * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
+ * name, `raw(expression)`, or an options object - reach the dialects as one.
+ */
+export declare function normalizeIndexColumn(entry: IndexColumnInput): IndexColumnSchema;

package/dist/util/indexColumn.util.js

@@ -0,0 +1,26 @@
+import { QueryRaw, RAW_VALUE } from '../type/index.js';
+/**
+ * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
+ * name, `raw(expression)`, or an options object - reach the dialects as one.
+ */
+export function normalizeIndexColumn(entry) {
+    if (typeof entry === 'string') {
+        return { column: entry };
+    }
+    if (entry instanceof QueryRaw) {
+        return { column: rawSql(entry), expression: true };
+    }
+    const { column, ...rest } = entry;
+    return column instanceof QueryRaw ? { ...rest, column: rawSql(column), expression: true } : { ...rest, column };
+}
+/**
+ * An index expression is DDL, evaluated once at creation time, so it cannot take the dialect-aware
+ * callback form of `raw()` - there is no query context to hand it.
+ */
+function rawSql(value) {
+    const sql = value[RAW_VALUE];
+    if (typeof sql !== 'string') {
+        throw new TypeError('an index expression needs raw() with a string, not a function');
+    }
+    return sql;
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "Extremely fast, type-safe TypeScript ORM - one API for every database",
   "license": "MIT",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -44,6 +44,8 @@
       "default": "./dist/browser/uql-browser.min.js"
     },
     "./libsql": "./dist/libsql/index.js",
+    "./turso": "./dist/turso/index.js",
+    "./turso/local": "./dist/turso/local.js",
     "./neon": "./dist/neon/index.js",
     "./d1": "./dist/d1/index.js",
     "./bunSql": "./dist/bunSql/index.js",
@@ -66,6 +68,8 @@
     "@neondatabase/serverless": ">=0.9.0",
     "@nestjs/common": ">=10.0.0",
     "@nestjs/core": ">=10.0.0",
+    "@tursodatabase/database": ">=0.7.0",
+    "@tursodatabase/serverless": ">=1.0.0",
     "better-sqlite3": ">=9.0.0",
     "express": ">=5.0.0",
     "jiti": ">=2.0.0",
@@ -90,6 +94,12 @@
     "@nestjs/core": {
       "optional": true
     },
+    "@tursodatabase/database": {
+      "optional": true
+    },
+    "@tursodatabase/serverless": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
     },
@@ -127,9 +137,11 @@
     "@nestjs/common": "^11.1.28",
     "@nestjs/core": "^11.1.28",
     "@nestjs/testing": "^11.1.28",
+    "@tursodatabase/database": "^0.7.2",
+    "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.6",
-    "@types/pg": "^8.20.0",
+    "@types/pg": "^8.20.1",
     "@types/ws": "^8.18.1",
     "better-sqlite3": "^13.0.2",
     "express": "^5.2.1",
@@ -141,6 +153,7 @@
     "pg-query-stream": "^4.16.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
+    "sqlite-vec": "^0.1.9",
     "ws": "^8.21.1"
   },
   "author": "Roger Padilla",
@@ -194,5 +207,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1d056e8d5030fe70e3dc21a151db282e9e553dd9"
+  "gitHead": "0804fc0205c1f629e497df020835a17b63aed0e8"
 }

package/dist/migrate/codegen/entityMerger.d.ts

@@ -1,114 +0,0 @@
-/**
- * Entity Merger
- *
- * Merges generated entity code with existing TypeScript entity files.
- * Uses string-based parsing to add new fields with JSDoc comments.
- */
-import type { ColumnNode, RelationshipNode } from '../../schema/types.js';
-/**
- * Options for entity merging.
- */
-export interface EntityMergerOptions {
-    /** Add JSDoc @sync-added comments to new fields */
-    addSyncComments?: boolean;
-    /** Mark removed fields with @deprecated instead of deleting */
-    markRemovedAsDeprecated?: boolean;
-    /** Custom property name transformer */
-    propertyNameTransformer?: (columnName: string) => string;
-}
-/**
- * Represents a field to add to an entity.
- */
-export interface FieldToAdd {
-    column: ColumnNode;
-    propertyName: string;
-    isRelation?: boolean;
-    relation?: RelationshipNode;
-}
-/**
- * Represents a field to mark as deprecated.
- */
-export interface FieldToDeprecate {
-    propertyName: string;
-    reason: string;
-}
-/**
- * Result of entity merge operation.
- */
-export interface MergeResult {
-    /** The merged source code */
-    code: string;
-    /** Number of fields added */
-    fieldsAdded: number;
-    /** Number of fields marked deprecated */
-    fieldsDeprecated: number;
-    /** Whether the file was modified */
-    modified: boolean;
-}
-/**
- * Merges new fields from database schema into existing entity files.
- */
-export declare class EntityMerger {
-    private readonly options;
-    constructor(options?: EntityMergerOptions);
-    /**
-     * Merge new fields into existing entity source code.
-     */
-    merge(existingCode: string, fieldsToAdd: FieldToAdd[], fieldsToDeprecate?: FieldToDeprecate[]): MergeResult;
-    /**
-     * Extract existing property names from entity code.
-     */
-    private extractPropertyNames;
-    /**
-     * Find the position to insert new fields (before the last closing brace).
-     */
-    private findInsertPosition;
-    /**
-     * Count net brace depth change in a line.
-     */
-    private countBraces;
-    /**
-     * Generate code for new fields.
-     */
-    private generateFieldsCode;
-    /**
-     * Generate code for a column field.
-     */
-    private generateColumnField;
-    /**
-     * Generate code for a relation field.
-     */
-    private generateRelationField;
-    /**
-     * Mark a field as deprecated in the source code.
-     */
-    private markFieldAsDeprecated;
-    /**
-     * Build Field decorator options string.
-     */
-    private buildFieldOptions;
-    /**
-     * Format type for description.
-     */
-    private formatTypeDescription;
-    /**
-     * Get relation decorator name.
-     */
-    private getRelationDecoratorName;
-    /**
-     * Default property name transformer (delegates to shared utility).
-     */
-    private defaultPropertyNameTransformer;
-    /**
-     * Convert to PascalCase (delegates to shared utility).
-     */
-    private toPascalCase;
-    /**
-     * Singularize (delegates to shared utility).
-     */
-    private singularize;
-}
-/**
- * Create an EntityMerger instance.
- */
-export declare function createEntityMerger(options?: EntityMergerOptions): EntityMerger;