uql-orm 0.23.0 → 0.24.0

package/README.md

@@ -32,8 +32,9 @@
 npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @tursodatabase/serverless, @libsql/client
 ```
 
-Decorators also need `reflect-metadata` ([setup](https://uql-orm.dev/getting-started)); the
-[imperative API](https://uql-orm.dev/entities/imperative) needs nothing extra.
+That is the whole install. Decorators are the standard TC39 ones, so there is no `reflect-metadata`
+and no compiler flag to turn on ([setup](https://uql-orm.dev/getting-started)), and the
+[imperative API](https://uql-orm.dev/entities/imperative) skips decorators altogether.
 
 ```ts
 await querier.findMany(User, {
@@ -55,8 +56,7 @@ from the browser to the server. The same object runs on every supported database
 - **Type-safe to the leaf.** Operators are gated per field type, and JSON/JSONB dot-paths resolve each path's value type, so `{ age: { $like: 'x' } }` or a typo'd path is a compile error instead of a runtime surprise.
 - **No codegen.** Entities are TypeScript classes, so your code *is* the schema. No `.prisma` file to regenerate, no generated client to keep in sync.
 - **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, LibSQL, Neon, Cloudflare D1, Bun SQL, and MongoDB.
-- **First ORM with a native Turso driver.** Turso Cloud over pure `fetch()` with zero native dependencies, so it runs on Cloudflare Workers and Vercel Edge, plus the embedded Rust engine for local-first apps.
-- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [non-bypassable multi-tenant filters](https://uql-orm.dev/multi-tenancy), [entity-first migrations](https://uql-orm.dev/migrations), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/extensions-http).
+- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [non-bypassable multi-tenant filters](https://uql-orm.dev/multi-tenancy), [entity-first migrations](https://uql-orm.dev/migrations), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/http).
 
 ## Get started
 

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, TransactionOptions, Type } from '../type/index.js';
+import type { ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -27,9 +27,26 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     findOneById<E extends object>(entity: Type<E>, id: IdValue<E>, q?: QueryOne<E>, opts?: QueryOptions): Promise<E | undefined>;
     findOne<E extends object>(entity: Type<E>, q: QueryOne<E>, opts?: QueryOptions): Promise<E | undefined>;
     findMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
+    /**
+     * The connection outlives the call here: it is held until the iterator is drained or closed by a
+     * `break`/`throw`. Abandoning the iterator instead leaks it until GC, so consume it in a `for await`.
+     */
+    findManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<E>;
     findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
+    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
+    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
+    restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
     /**
      * end the pool.
      */

package/dist/querier/abstractQuerierPool.js

@@ -1,3 +1,55 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { withContext } from '../context/context.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
@@ -43,6 +95,26 @@ export class AbstractQuerierPool {
     findMany(entity, q, opts) {
         return this.withQuerier((querier) => querier.findMany(entity, q, opts));
     }
+    /**
+     * The connection outlives the call here: it is held until the iterator is drained or closed by a
+     * `break`/`throw`. Abandoning the iterator instead leaks it until GC, so consume it in a `for await`.
+     */
+    async *findManyStream(entity, q, opts) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const querier = __addDisposableResource(env_1, await this.getQuerier(), true);
+            yield* querier.findManyStream(entity, q, opts);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    }
     findManyAndCount(entity, q, opts) {
         return this.withQuerier((querier) => querier.findManyAndCount(entity, q, opts));
     }
@@ -52,4 +124,40 @@ export class AbstractQuerierPool {
     aggregate(entity, q, opts) {
         return this.withQuerier((querier) => querier.aggregate(entity, q, opts));
     }
+    insertOne(entity, payload) {
+        return this.withQuerier((querier) => querier.insertOne(entity, payload));
+    }
+    insertMany(entity, payload) {
+        return this.withQuerier((querier) => querier.insertMany(entity, payload));
+    }
+    updateOneById(entity, id, payload, opts) {
+        return this.withQuerier((querier) => querier.updateOneById(entity, id, payload, opts));
+    }
+    updateMany(entity, q, payload, opts) {
+        return this.withQuerier((querier) => querier.updateMany(entity, q, payload, opts));
+    }
+    upsertOne(entity, conflictPaths, payload) {
+        return this.withQuerier((querier) => querier.upsertOne(entity, conflictPaths, payload));
+    }
+    upsertMany(entity, conflictPaths, payload) {
+        return this.withQuerier((querier) => querier.upsertMany(entity, conflictPaths, payload));
+    }
+    saveOne(entity, payload) {
+        return this.withQuerier((querier) => querier.saveOne(entity, payload));
+    }
+    saveMany(entity, payload) {
+        return this.withQuerier((querier) => querier.saveMany(entity, payload));
+    }
+    deleteOneById(entity, id, opts) {
+        return this.withQuerier((querier) => querier.deleteOneById(entity, id, opts));
+    }
+    deleteMany(entity, q, opts) {
+        return this.withQuerier((querier) => querier.deleteMany(entity, q, opts));
+    }
+    restoreOneById(entity, id) {
+        return this.withQuerier((querier) => querier.restoreOneById(entity, id));
+    }
+    restoreMany(entity, q) {
+        return this.withQuerier((querier) => querier.restoreMany(entity, q));
+    }
 }

package/dist/querier/abstractSqlQuerier.js

@@ -64,6 +64,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         if (toManyKeys.length) {
             throw new TypeError(`findManyStream does not load to-many relations (${toManyKeys.join(', ')}). Use findMany so fillToManyRelations can run, or omit those keys from the stream query.`);
         }
+        // The one path that does not go through `all`/`run`, so it connects on its own: streaming first on
+        // a freshly acquired querier used to reach `getConn()` with nothing acquired.
+        await this.lazyConnect();
         const ctx = this.dialect.createContext();
         this.dialect.find(ctx, entity, q, opts);
         const normalizedParams = this.dialect.normalizeValues(ctx.values);

package/dist/type/querier.d.ts

@@ -1,11 +1,10 @@
 import type { Db } from 'mongodb';
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SqlDialectName } from './dialect.js';
-import type { HookEvent, IdValue, UpdatePayload } from './entity.js';
+import type { HookEvent } from './entity.js';
 import type { LoggingOptions } from './logger.js';
 import type { NamingStrategy } from './namingStrategy.js';
-import type { Query, QueryConflictPaths, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
-import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
+import type { Query, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
 import type { UniversalQuerier } from './universalQuerier.js';
 import type { Type } from './utility.js';
 /**
@@ -56,34 +55,6 @@ export interface Querier extends UniversalQuerier {
     count<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    /**
-     * Insert a single record and return its ID (provided, `onInsert`-generated, or
-     * database-generated - see {@link Querier.insertMany} for the exact semantics).
-     * Returns `undefined` when the ID cannot be determined (e.g. MySQL/SQLite non-auto-increment
-     * keys in batches without explicit IDs).
-     */
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    /**
-     * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
-     * dialect's bind-parameter limit) and return their IDs in payload order.
-     *
-     * Provided IDs and client-generated ones (`@Id({ onInsert })`) are always returned as-is.
-     * Database-generated IDs are exact on `'returning'` dialects (Postgres, MariaDB, MongoDB);
-     * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
-     * auto-increment keys in batches without explicit IDs - otherwise those entries are
-     * `undefined` rather than potentially wrong values.
-     */
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
-     * entity has no soft-delete field.
-     */
-    restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
-    restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
     /**
      * Delete many records (soft-deletes when the entity has a soft-delete field, else removes them).
      * Supports both entity-as-argument and entity-as-field patterns.
@@ -92,10 +63,6 @@ export interface Querier extends UniversalQuerier {
     deleteMany<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    /**
-     * Run an aggregate query (GROUP BY with aggregate functions).
-     */
-    aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     /**
      * whether this querier is in a transaction or not.
      */

package/dist/type/querierPool.d.ts

@@ -15,24 +15,25 @@ export interface PoolRunOptions {
 /**
  * Querier pool. Read the dialect id via `pool.dialect.dialectName` (see {@link AbstractDialect.dialectName}); queriers expose the same on `querier.dialect`.
  *
- * The read methods of {@link UniversalQuerier} are available directly on the pool. Each call
- * acquires its own querier, runs the single read, and releases it - so
- * `Promise.all([pool.findMany(A, {}), pool.count(B, {})])` runs on separate connections in
- * parallel, while the same calls inside one `withQuerier`/`transaction` callback share a pinned
- * connection and serialize. Single-connection backends (better-sqlite3, Bun sqlite, D1) stay
- * correct but always serialize on their one connection.
+ * A pool is a {@link UniversalQuerier} too, so a function that runs queries takes that type and the
+ * caller passes its own querier or the pool. `pool.op(...)` is exactly
+ * `pool.withQuerier((querier) => querier.op(...))`, so two pool calls are two units of work; when they
+ * must commit together, that is `transaction`.
  *
- * An enclosing `withContext` scopes the pool reads (`security` filters apply); one wrapper covers a
- * whole parallel fan-out, which is why the reads take no per-call `context` option (unlike
- * `withQuerier`/`transaction`).
+ * Acquiring per call is also what makes `Promise.all([pool.findMany(A, {}), pool.count(B, {})])` run on
+ * separate connections, while the same calls inside one `withQuerier`/`transaction` share a pinned
+ * connection and serialize. Single-connection backends (better-sqlite3, Bun sqlite, D1) stay correct
+ * but always serialize.
  *
- * Pool reads take the entity-as-argument form only. For the `{ $entity }` form, streaming, or
- * writes (they need a unit of work), use `withQuerier`/`transaction`.
+ * An enclosing `withContext` scopes pool calls (`security` filters apply), which is why they take no
+ * per-call `context` option (unlike `withQuerier`/`transaction`).
+ *
+ * Pool calls take the entity-as-argument form only; the `{ $entity }` form needs a querier.
  *
  * @typeParam Q - Querier implementation returned from the pool.
  * @typeParam D - Concrete dialect class held by the pool.
  */
-export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDialect = AbstractDialect> extends Pick<UniversalQuerier, 'findOneById' | 'findOne' | 'findMany' | 'findManyAndCount' | 'count' | 'aggregate'> {
+export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDialect = AbstractDialect> extends UniversalQuerier {
     /**
      * Database dialect instance (single source of truth for dialect id and SQL/NoSQL behavior).
      */

package/dist/type/universalQuerier.d.ts

@@ -53,19 +53,29 @@ export interface UniversalQuerier {
      */
     count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     /**
-     * inserts a record.
+     * Insert a single record and return its ID (provided, `onInsert`-generated, or
+     * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).
+     * Returns `undefined` when the ID cannot be determined (e.g. MySQL/SQLite non-auto-increment
+     * keys in batches without explicit IDs).
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the ID
      */
     insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
     /**
-     * Inserts many records.
+     * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
+     * dialect's bind-parameter limit) and return their IDs in payload order.
+     *
+     * Provided IDs and client-generated ones (`@Id({ onInsert })`) are always returned as-is.
+     * Database-generated IDs are exact on `'returning'` dialects (Postgres, MariaDB, MongoDB);
+     * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
+     * auto-increment keys in batches without explicit IDs - otherwise those entries are
+     * `undefined` rather than potentially wrong values.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    insertMany?<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
     /**
      * updates a record partially.
      * @param entity the entity to persist on
@@ -81,7 +91,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return the number of affected records
      */
-    updateMany?<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Insert or update a record based on the conflict paths.
      * @param entity the entity to persist on
@@ -89,7 +99,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertOne?<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
     /**
      * Insert or update many records based on the conflict paths.
      * @param entity the entity to persist on
@@ -97,7 +107,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertMany?<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
     /**
      * insert or update a record.
      * @param entity the entity to persist on
@@ -111,7 +121,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany?<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
     /**
      * delete or SoftDelete a record.
      * @param entity the entity to persist on
@@ -126,6 +136,12 @@ export interface UniversalQuerier {
      * @return the number of affected records
      */
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
+     * entity has no soft-delete field.
+     */
+    restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
+    restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
     /**
      * runs an aggregate query (GROUP BY with aggregate functions).
      * @param entity the target entity

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.23.0",
+  "version": "0.24.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -145,7 +145,6 @@
     "pg-query-stream": "^4.16.0",
     "rxjs": "^7.8.2",
     "sqlite-vec": "^0.1.9",
-    "tsx": "^4.23.1",
     "ws": "^8.21.1"
   },
   "author": "Roger Padilla",
@@ -199,5 +198,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3bfca5950ac564b8503fb2140726501b01825b9d"
+  "gitHead": "d9499a4b8c5ee866950b397fb87f55643d86fc39"
 }