uql-orm 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -1,9 +1,33 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.4.5](https://github.com/rogerpadilla/uql/compare/uql-orm@0.4.0...uql-orm@0.4.5) (2026-03-14)
+
+
+### Features
+
+* add vector search integration tests for `findMany` with `$sort: { $vector }` and update test infrastructure. ([c920cde](https://github.com/rogerpadilla/uql/commit/c920cde46dbb4985d07a1926dfc3ac845862244c))
+* implement cursor-based stream with  across all queriers and deprecate  in favor of ([2d6c2ea](https://github.com/rogerpadilla/uql/commit/2d6c2ea0851d9c20ca9d092717087eaa65e5f937))
+* upgrade to Vite 8 and TypeScript 6, removing redundant compiler options and `vite-tsconfig-paths` plugin. ([f81563c](https://github.com/rogerpadilla/uql/commit/f81563cfe5246bfa59966f08493fd9786a817e02))
+
+
+
+
+
 # Changelog
 
 All notable changes to this project will be documented in this file. Please add new changes to the top.
 
 date format is [yyyy-mm-dd]
 
+## [0.4.5] - 2026-03-14
+### Testing
+- **Vector search integration tests**: Added 7 end-to-end tests for `findMany` with `$sort: { $vector }` against a real Postgres+pgvector database — covers cosine/L2 similarity ordering, `$project` distance projection, filter+sort combo, `$limit`, and empty-table edge case.
+- Docker Postgres image switched to `pgvector/pgvector:pg18` for pgvector extension support.
+- Test DDL generator now handles `vector`, `halfvec`, and `sparsevec` column types.
+
 ## [0.4.4] - 2026-03-14
 ### Dependencies
 - **Vite 7 → 8**: Upgraded to Vite 8 (powered by Rolldown), replacing the `vite-tsconfig-paths` plugin with Vite's built-in `resolve.tsconfigPaths` option.

package/dist/browser/uql-browser.min.js

@@ -1,181 +1,207 @@
-import { _ as _apply_decs_2203_r } from './cc-BEf4wTUm.js';
-import { randomUUID } from 'node:crypto';
-import { Id, Field, ManyToOne, Entity, OneToOne, OneToMany, ManyToMany } from '../entity/index.js';
-import '../type/index.js';
-import { raw, lowerFirst, upperFirst, getKeys } from '../util/index.js';
-import 'reflect-metadata';
+import sqlstring from 'sqlstring-sqlite';
+import { AbstractSqlDialect } from '../dialect/index.js';
+import { getMeta } from '../entity/index.js';
+import { hasKeys } from '../util/index.js';
+import { AbstractSqlQuerier, AbstractQuerierPool } from '../querier/index.js';
 
-var _dec, _dec1, _dec2, _dec3, _dec4, _dec5, _dec6, /**
-   * auto-generated primary-key (when the `onInsert` property is omitted).
-   */ _init_id, /**
-   * foreign-keys are really simple to specify with the `reference` property.
-   */ _init_companyId, /**
-   * The `Relation` wrapper type can be used in ESM projects for the relations to
-   * avoid circular dependency issues.
-   */ _init_company, _init_creatorId, _init_creator, /**
-   * 'onInsert' property can be used to specify a custom mechanism for
-   * obtaining the value of a field when inserting:
-   */ _init_createdAt, /**
-   * 'onUpdate' property can be used to specify a custom mechanism for
-   * obtaining the value of a field when updating:
-   */ _init_updatedAt, _initProto, _dec7, _initClass, _BaseEntity, _dec8, _dec9, _dec10, _init_name, _init_description, _init_kind, _initProto1, _dec11, _initClass1, _BaseEntity1, _dec12, _dec13, /**
-   * an entity can specify its own ID Field and still inherit the others
-   * columns/relations from its parent entity.
-   */ _init_pk, _init_picture, _initProto2, _dec14, _initClass2, _BaseEntity2, _dec15, _dec16, _dec17, _dec18, _dec19, _init_name1, _init_email, _init_password, /**
-   * `mappedBy` property can be a callback or a string (callback is useful for auto-refactoring).
-   */ _init_profile, _init_users, _initProto3, _dec20, _initClass3, _dec21, _dec22, _init_id1, _init_name2, _initProto4, _dec23, _initClass4, _BaseEntity3, _dec24, _dec25, _dec26, _dec27, _init_name3, _init_description1, _init_parentLedgerId, _init_parentLedger, _initProto5, _dec28, _initClass5, _BaseEntity4, _dec29, _dec30, _dec31, /**
-   * an entity can override the ID Field and still inherit the others
-   * columns/relations from its parent entity.
-   * 'onInsert' property can be used to specify a custom mechanism for
-   * auto-generating the primary-key's value when inserting.
-   */ _init_pk1, _init_name4, _init_description2, _initProto6, _dec32, _initClass6, _BaseEntity5, _dec33, _dec34, _dec35, _dec36, _dec37, _init_name5, _init_percentage, _init_categoryId, _init_category, _init_description3, _initProto7, _dec38, _initClass7, _BaseEntity6, _dec39, _dec40, _dec41, _init_name6, _init_measureUnits, /**
-   * `onDelete` callback allows to specify which field will be used when deleting/querying this entity.
-   */ _init_deletedAt, _initProto8, _dec42, _initClass8, _BaseEntity7, _dec43, _dec44, _dec45, _dec46, _init_name7, _init_categoryId1, _init_category1, _init_deletedAt1, _initProto9, _dec47, _initClass9, _BaseEntity8, _dec48, _dec49, _dec50, _init_name8, _init_address, _init_description4, _initProto10, _dec51, _initClass10, _BaseEntity9, _dec52, _dec53, _dec54, _dec55, _dec56, _dec57, _dec58, _dec59, _dec60, _dec61, _dec62, _dec63, _dec64, _dec65, _dec66, _init_name9, _init_description5, _init_code, _init_buyLedgerAccountId, _init_buyLedgerAccount, _init_saleLedgerAccountId, _init_saleLedgerAccount, _init_taxId, _init_tax, _init_measureUnitId, _init_measureUnit, _init_salePrice, _init_inventoryable, _init_tags, _init_tagsCount, _initProto11, _dec67, _initClass11, _BaseEntity10, _dec68, _dec69, _dec70, _init_name10, _init_items, _init_itemsCount, _initProto12, _dec71, _initClass12, _dec72, _dec73, _dec74, _init_id2, _init_itemId, _init_tagId, _initProto13, _dec75, _initClass13, _BaseEntity11, _dec76, _dec77, _dec78, _init_itemAdjustments, _init_date, _init_description6, _initProto14, _dec79, _initClass14, _BaseEntity12, _dec80, _dec81, _dec82, _dec83, _dec84, _dec85, _dec86, _dec87, _init_itemId1, _init_item, _init_number, _init_buyPrice, _init_storehouseId, _init_storehouse, _init_inventoryAdjustmentId, _init_inventoryAdjustment, _initProto15;
-_dec = Id(), _dec1 = Field({
-    references: ()=>_Company
-}), _dec2 = ManyToOne({
-    entity: ()=>_Company
-}), _dec3 = Field({
-    references: ()=>_User
-}), _dec4 = ManyToOne({
-    entity: ()=>_User
-}), _dec5 = Field({
-    onInsert: Date.now
-}), _dec6 = Field({
-    onUpdate: Date.now
-});
-/**
- * an `abstract` class can (optionally) be used as the base "template" for the entities
- * (so common fields' declaration is easily reused).
- */ class BaseEntity {
-    static{
-        ({ e: [_init_id, _init_companyId, _init_company, _init_creatorId, _init_creator, _init_createdAt, _init_updatedAt, _initProto] } = _apply_decs_2203_r(this, [
-            [
-                _dec,
-                0,
-                "id"
-            ],
-            [
-                _dec1,
-                0,
-                "companyId"
-            ],
-            [
-                _dec2,
-                0,
-                "company"
-            ],
-            [
-                _dec3,
-                0,
-                "creatorId"
-            ],
-            [
-                _dec4,
-                0,
-                "creator"
-            ],
-            [
-                _dec5,
-                0,
-                "createdAt"
-            ],
-            [
-                _dec6,
-                0,
-                "updatedAt"
-            ]
-        ], []));
+class SqliteDialect extends AbstractSqlDialect {
+    constructor(namingStrategy){
+        super('sqlite', namingStrategy);
+    }
+    addValue(values, value) {
+        if (value instanceof Date) {
+            value = value.getTime();
+        } else if (typeof value === 'boolean') {
+            value = value ? 1 : 0;
+        }
+        return super.addValue(values, value);
+    }
+    compare(ctx, entity, key, val, opts) {
+        if (key === '$text') {
+            const meta = getMeta(entity);
+            const search = val;
+            const fields = search.$fields.map((fKey)=>{
+                const field = meta.fields[fKey];
+                const columnName = this.resolveColumnName(fKey, field);
+                return this.escapeId(columnName);
+            });
+            const tableName = this.resolveTableName(entity, meta);
+            ctx.append(`${this.escapeId(tableName)} MATCH {${fields.join(' ')}} : `);
+            ctx.addValue(search.$value);
+            return;
+        }
+        super.compare(ctx, entity, key, val, opts);
     }
-    constructor(){
-        this.id = (_initProto(this), _init_id(this));
-        this.companyId = _init_companyId(this);
-        this.company = _init_company(this);
-        this.creatorId = _init_creatorId(this);
-        this.creator = _init_creator(this);
-        this.createdAt = _init_createdAt(this);
-        this.updatedAt = _init_updatedAt(this);
-    }
-}
-let _Company;
-_dec7 = Entity(), _dec8 = Field(), _dec9 = Field(), _dec10 = Field({
-    type: 'jsonb'
-});
-class Company extends (_BaseEntity = BaseEntity) {
-    static{
-        ({ e: [_init_name, _init_description, _init_kind, _initProto1], c: [_Company, _initClass] } = _apply_decs_2203_r(this, [
-            [
-                _dec8,
-                0,
-                "name"
-            ],
-            [
-                _dec9,
-                0,
-                "description"
-            ],
-            [
-                _dec10,
-                0,
-                "kind"
-            ]
-        ], [
-            _dec7
-        ], _BaseEntity));
+    compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
+        switch(op){
+            case '$elemMatch':
+                this.buildElemMatchCondition(ctx, entity, key, val, opts);
+                break;
+            case '$all':
+                {
+                    // SQLite: Check JSON array contains all values using multiple json_each subqueries
+                    const values = val;
+                    const conditions = values.map((v)=>{
+                        ctx.pushValue(JSON.stringify(v));
+                        return `EXISTS (SELECT 1 FROM json_each(${this.escapeId(key)}) WHERE value = json(?))`;
+                    }).join(' AND ');
+                    ctx.append(`(${conditions})`);
+                    break;
+                }
+            case '$size':
+                // SQLite: Check JSON array length
+                // e.g., json_array_length(roles) = 3, or json_array_length(roles) >= 2
+                this.buildSizeComparison(ctx, ()=>{
+                    ctx.append('json_array_length(');
+                    this.getComparisonKey(ctx, entity, key, opts);
+                    ctx.append(')');
+                }, val);
+                break;
+            default:
+                super.compareFieldOperator(ctx, entity, key, op, val, opts);
+        }
+    }
+    /**
+   * Build $elemMatch condition for SQLite JSON arrays.
+   * Uses EXISTS with json_each and supports nested operators.
+   */ buildElemMatchCondition(ctx, _entity, key, match, opts) {
+        ctx.append('EXISTS (SELECT 1 FROM json_each(');
+        this.getComparisonKey(ctx, _entity, key, opts);
+        ctx.append(') WHERE ');
+        const conditions = [];
+        for (const [field, value] of Object.entries(match)){
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                // Value is an operator object
+                const ops = value;
+                for (const [op, opVal] of Object.entries(ops)){
+                    conditions.push(this.buildJsonFieldOperator(ctx, field, op, opVal));
+                }
+            } else {
+                // Simple equality
+                ctx.pushValue(value);
+                conditions.push(`json_extract(value, '$.${field}') = ?`);
+            }
+        }
+        ctx.append(conditions.join(' AND '));
+        ctx.append(')');
+    }
+    /**
+   * Build a comparison condition for a JSON field with an operator.
+   */ buildJsonFieldOperator(ctx, field, op, value) {
+        return this.buildJsonFieldCondition(ctx, {
+            ...this.getBaseJsonConfig(),
+            fieldAccessor: (f)=>`json_extract(value, '$.${f}')`
+        }, field, op, value);
+    }
+    getJsonFieldConfig(escapedColumn, jsonPath) {
+        return {
+            ...this.getBaseJsonConfig(),
+            fieldAccessor: ()=>`json_extract(${escapedColumn}, '$.${jsonPath}')`
+        };
+    }
+    getBaseJsonConfig() {
+        return {
+            ...super.getBaseJsonConfig(),
+            numericCast: (expr)=>`CAST(${expr} AS REAL)`,
+            neExpr: (f, ph)=>`${f} IS NOT ${ph}`
+        };
+    }
+    upsert(ctx, entity, conflictPaths, payload) {
+        this.onConflictUpsert(ctx, entity, conflictPaths, payload, this.insert.bind(this));
+    }
+    formatJsonMerge(ctx, escapedCol, value) {
+        let expr = escapedCol;
+        if (hasKeys(value.$merge)) {
+            ctx.pushValue(JSON.stringify(value.$merge));
+            expr = `json_patch(COALESCE(${escapedCol}, '{}'), ?)`;
+        }
+        if (value.$unset?.length) {
+            const paths = value.$unset.map((k)=>`'$.${this.escapeJsonKey(k)}'`).join(', ');
+            expr = `json_remove(${expr}, ${paths})`;
+        }
+        ctx.append(`${escapedCol} = ${expr}`);
     }
     static{
-        _initClass();
+        /** sqlite-vec distance functions. */ this.VECTOR_FNS = {
+            cosine: 'vec_distance_cosine',
+            l2: 'vec_distance_L2',
+            hamming: 'vec_distance_hamming'
+        };
     }
-    constructor(...args){
-        super(...args), this.name = (_initProto1(this), _init_name(this)), this.description = _init_description(this), this.kind = _init_kind(this);
+    /** Emit a sqlite-vec distance function: `vec_distance_<metric>(col, ?)`. */ appendVectorSort(ctx, meta, key, search) {
+        this.appendFunctionVectorSort(ctx, meta, key, search, SqliteDialect.VECTOR_FNS, 'SQLite');
+    }
+    escape(value) {
+        return sqlstring.escape(value);
     }
 }
-let _Profile;
-_dec11 = Entity({
-    name: 'user_profile'
-}), _dec12 = Id(), _dec13 = Field({
-    name: 'image'
-});
-class Profile extends (_BaseEntity1 = BaseEntity) {
-    static{
-        ({ e: [_init_pk, _init_picture, _initProto2], c: [_Profile, _initClass1] } = _apply_decs_2203_r(this, [
-            [
-                _dec12,
-                0,
-                "pk"
-            ],
-            [
-                _dec13,
-                0,
-                "picture"
-            ]
-        ], [
-            _dec11
-        ], _BaseEntity1));
+
+class AbstractSqliteQuerier extends AbstractSqlQuerier {
+    buildUpdateResult(changes, lastInsertRowid) {
+        const firstId = lastInsertRowid ? Number(lastInsertRowid) - (changes - 1) : undefined;
+        const ids = firstId ? Array(changes).fill(firstId).map((i, index)=>i + index) : [];
+        return {
+            changes,
+            ids,
+            firstId
+        };
     }
-    static{
-        _initClass1();
+}
+
+class SqliteQuerier extends AbstractSqliteQuerier {
+    constructor(db, extra){
+        super(new SqliteDialect(extra?.namingStrategy), extra), this.db = db, this.extra = extra;
     }
-    constructor(...args){
-        super(...args), this.pk = (_initProto2(this), _init_pk(this)), this.picture = _init_picture(this);
+    async internalAll(query, values) {
+        return this.db.prepare(query).all(values || []);
+    }
+    async *internalStream(query, values) {
+        for (const row of this.db.prepare(query).iterate(values || [])){
+            yield row;
+        }
+    }
+    async internalRun(query, values) {
+        const { changes, lastInsertRowid } = this.db.prepare(query).run(values || []);
+        return this.buildUpdateResult(changes, lastInsertRowid);
+    }
+    async internalRelease() {
+        if (this.hasOpenTransaction) {
+            throw TypeError('pending transaction');
+        }
+    // no-op
     }
 }
-let _User;
-_dec14 = Entity(), _dec15 = Field(), _dec16 = Field({
-    updatable: false
-}), _dec17 = Field({
-    eager: false
-}), _dec18 = OneToOne({
-    entity: ()=>_Profile,
-    mappedBy: (profile)=>profile.creator,
-    cascade: true
-}), _dec19 = OneToMany({
-    entity: ()=>_User,
-    mappedBy: 'creator'
-});
-class User extends (_BaseEntity2 = BaseEntity) {
-    static{
-        ({ e: [_init_name1, _init_email, _init_password, _init_profile, _init_users, _initProto3], c: [_User, _initClass2] } = _apply_decs_2203_r(this, [
+
+class Sqlite3QuerierPool extends AbstractQuerierPool {
+    constructor(filename, opts, extra){
+        super('sqlite', extra), this.filename = filename, this.opts = opts;
+    }
+    async getQuerier() {
+        if (!this.querier) {
+            let db;
+            if (typeof Bun !== 'undefined') {
+                const { Database: BunDatabase } = await import('bun:sqlite');
+                const bunDb = new BunDatabase(this.filename, this.opts);
+                bunDb.run('PRAGMA journal_mode = WAL');
+                db = bunDb;
+            } else {
+                const { default: BetterSqlite3 } = await import('better-sqlite3');
+                db = new BetterSqlite3(this.filename, this.opts);
+                db.pragma('journal_mode = WAL');
+            }
+            this.querier = new SqliteQuerier(db, this.extra);
+        }
+        return this.querier;
+    }
+    async end() {
+        await this.querier?.db.close();
+        this.querier = undefined;
+    }
+}
+
+export { Sqlite3QuerierPool, SqliteDialect, SqliteQuerier };
+//# sourceMappingURL=uql-browser.min.js.map
+1, _init_email, _init_password, _init_profile, _init_users, _initProto3], c: [_User, _initClass2] } = _apply_decs_2203_r(this, [
             [
                 _dec15,
                 0,
@@ -772,6 +798,42 @@ class ItemAdjustment extends (_BaseEntity12 = BaseEntity) {
         super(...args), this.itemId = (_initProto15(this), _init_itemId1(this)), this.item = _init_item(this), this.number = _init_number(this), this.buyPrice = _init_buyPrice(this), this.storehouseId = _init_storehouseId(this), this.storehouse = _init_storehouse(this), this.inventoryAdjustmentId = _init_inventoryAdjustmentId(this), this.inventoryAdjustment = _init_inventoryAdjustment(this);
     }
 }
+let _VectorItem;
+_dec88 = Entity(), _dec89 = Id(), _dec90 = Field(), _dec91 = Field({
+    type: 'vector',
+    dimensions: 3
+});
+class VectorItem {
+    static{
+        ({ e: [_init_id3, _init_name11, _init_vec, _initProto16], c: [_VectorItem, _initClass15] } = _apply_decs_2203_r(this, [
+            [
+                _dec89,
+                0,
+                "id"
+            ],
+            [
+                _dec90,
+                0,
+                "name"
+            ],
+            [
+                _dec91,
+                0,
+                "vec"
+            ]
+        ], [
+            _dec88
+        ]));
+    }
+    static{
+        _initClass15();
+    }
+    constructor(){
+        this.id = (_initProto16(this), _init_id3(this));
+        this.name = _init_name11(this);
+        this.vec = _init_vec(this);
+    }
+}
 
 const holder = globalThis;
 const metaKey = Symbol.for('uql-orm/entity/decorator');
@@ -960,14 +1022,14 @@ function getDdlForTable(entity, querier, primaryKeyType) {
         let propSql = querier.dialect.escapeId(field.name) + ' ';
         if (field.isId) {
             propSql += field.onInsert ? `${insertableIdType} PRIMARY KEY` : primaryKeyType;
+        } else if (field.type === 'vector' || field.type === 'halfvec' || field.type === 'sparsevec') {
+            propSql += field.dimensions ? `${field.type}(${field.dimensions})` : field.type;
+        } else if (field.type === Number) {
+            propSql += 'BIGINT';
+        } else if (field.type === Date) {
+            propSql += 'TIMESTAMP';
         } else {
-            if (field.type === Number) {
-                propSql += 'BIGINT';
-            } else if (field.type === Date) {
-                propSql += 'TIMESTAMP';
-            } else {
-                propSql += defaultType;
-            }
+            propSql += defaultType;
         }
         return propSql;
     });
@@ -5380,5 +5442,5 @@ const hooks = {
     afterAll
 };
 
-export { BaseEntity, _Company as Company, _InventoryAdjustment as InventoryAdjustment, _Item as Item, _ItemAdjustment as ItemAdjustment, _ItemTag as ItemTag, _LedgerAccount as LedgerAccount, _MeasureUnit as MeasureUnit, _MeasureUnitCategory as MeasureUnitCategory, _Profile as Profile, _Storehouse as Storehouse, _Tag as Tag, _Tax as Tax, _TaxCategory as TaxCategory, _User as User, _UserWithNonUpdatableId as UserWithNonUpdatableId, clearTables, createSpec, createTables, dropTables };
+export { BaseEntity, _Company as Company, _InventoryAdjustment as InventoryAdjustment, _Item as Item, _ItemAdjustment as ItemAdjustment, _ItemTag as ItemTag, _LedgerAccount as LedgerAccount, _MeasureUnit as MeasureUnit, _MeasureUnitCategory as MeasureUnitCategory, _Profile as Profile, _Storehouse as Storehouse, _Tag as Tag, _Tax as Tax, _TaxCategory as TaxCategory, _User as User, _UserWithNonUpdatableId as UserWithNonUpdatableId, _VectorItem as VectorItem, clearTables, createSpec, createTables, dropTables };
 //# sourceMappingURL=uql-browser.min.js.map