@lossless.org/client 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": false,
   "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
   "exports": {
@@ -57,7 +57,7 @@
     "@push.rocks/smartstring": "^4.1.0",
     "@push.rocks/smarttime": "^4.2.3",
     "@push.rocks/smartunique": "^3.0.9",
-    "@push.rocks/taskbuffer": "^8.0.2",
+    "@push.rocks/taskbuffer": "^9.0.3",
     "@tsclass/tsclass": "^9.5.1",
     "minimatch": "^10.2.5",
     "mongodb": "^7.2.0"
@@ -81,15 +81,15 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.1039.0",
     "@clickhouse/client": "1.23.1",
-    "@git.zone/tsbuild": "4.5.0",
-    "@git.zone/tsrun": "2.0.6",
-    "@git.zone/tstest": "6.1.1",
+    "@git.zone/tsbuild": "5.0.0",
+    "@git.zone/tsrun": "3.0.0",
+    "@git.zone/tstest": "6.3.0",
     "@lossless.org/nosqldb": "8.0.2",
-    "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.5.0",
+    "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.6.0",
     "@lossless.org/objectstorage": "10.1.0",
     "@lossless.org/sqldb": "0.2.3",
     "@push.rocks/qenv": "^6.1.3",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.1",
     "mariadb": "3.5.4",
     "mongodb-memory-server": "11.1.0"
   },

package/readme.md

@@ -91,6 +91,8 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Identities on a migrated unique index | `@unI({ indexName })` names the index that backs the identity instead of `<field>_1` |
 | Typed `null` predicates | read and atomic filters accept `null` for a field declared optional, so a value stored as an explicit null stays addressable |
 | Owned sessions on cursors | `getCursor()` takes the handle from `db.createSession()` and keeps it leased until the cursor is closed |
+| Owned sessions on instance writes | `instance.save({ session })` and `instance.delete({ session })` take the handle from `db.createSession()`, leased for the one write like every other model API |
+| Typed connection pool options | `new SmartdataDb(options: ISmartdataDbOptions)` types `maxPoolSize`, `maxIdleTimeMS`, `serverSelectionTimeoutMS` and `socketTimeoutMS` beside the descriptor fields, so no cast through `IMongoDescriptor` is needed |
 | Named plural selectors | a non-empty `$in` anchors `atomicUpdateMany()`, `atomicDeleteMany()` and `atomicUpsertMany()`; singular operations are unchanged |
 | Fields only atomic writes may update | `@svDb({ atomicOnly: true })` and `atomicOnlyFields` — seeded by every write that creates the document, never overwritten by a later `save()` |
 | Defaults inside `$expr` | `{ $ifNull: ['$field', literal] }` operands, so a guard covers rows written before the field existed |
@@ -98,13 +100,14 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Identity rotation | `Model.atomicFindOneAndReplace(filter, replacement, opts?)` — the one write that moves an `@unI()` identity, under the matched document's `_id` |
 | Fail-fast on unprepared collections | a session-carrying call inside a transaction refuses instead of stalling on lazy index DDL until the client deadline |
 | Migration-owned indexes | `toleratedIndexNames` on the model — named undeclared indexes are observed, never created, dropped or verified, and no longer make the topology divergent |
+| Partial index filters in inspection | `inspectNamespace()`, `inspectCollectionTopology()` and `getIndexInfo()` report a partial index's `partialFilterExpression` exactly as the backend lists it, as a frozen snapshot present only on a partial index |
 | Key-value store readiness | `EasyStore.ensureInitialized()` — installs the store's declared index at startup, outside any transaction window, so a first `readKey()`/`writeKey()` needs no index DDL |
 
 `docs/source/smartdata/readme.md` documents each one with its refusals.
 
 ### Document APIs that need a MongoDB backend
 
-The document model runs on both NoSQLDB and MongoDB, but four APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.5.0 (see [Verification](#verification)); the two releases part on one row below — 10.5.0 groups composite keys exactly, 8.0.2 does not — and answer every other row alike.
+The document model runs on both NoSQLDB and MongoDB, but four APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.6.0 (see [Verification](#verification)); the two releases part on the grouped-totals and guarded-`$expr` rows below — 10.6.0 groups composite keys exactly and evaluates the guard, 8.0.2 does neither — and on whether a migration can create a partial index at all.
 
 `init()` asks the connected engine what it is with one `buildInfo` command and records the answer on the database as `engineIdentity` (`{ product, version }`). NoSQLDB answers with its own `nosqldb` identity document from 10.3.0 onward; a MongoDB server answers `buildInfo` without one; an engine that refuses the command — NoSQLDB 8.0.2 answers `CommandNotFound` — stays `{ product: 'unknown', version: null }`. The identity is what states `capabilities` on a plain `SmartdataDb`, and an unidentified engine states none at all, so every capability-gated call refuses. `NoSqlConnection` keeps stating the capabilities of its declared backend from construction on.
 
@@ -112,12 +115,12 @@ The document model runs on both NoSQLDB and MongoDB, but four APIs do not mean t
 | --- | --- | --- |
 | `getGroupedTotals()` / `getGroupedTotalsPage()` with one `groupBy` field | exact, including `sums` | exact |
 | the same with **two** `groupBy` fields | exact, `sums` included, on an engine that identifies itself as NoSQLDB 10.5.0 or newer: that release evaluates the composite group key per document. Below it the call is refused with `unsupported_operation` naming both fields and the single-field form, because the engine leaves the composite group key unresolved and answers with a single row whose group values are the literal field paths (`'$owner'`) and whose count is the whole filtered collection; the refusal is the guard against that wrong number, not a fix for it | exact |
-| guarded `$expr` atomic filters (`$add`, `$lte`, `$ifNull`) | refused by the engine: the fail-closed compilation uses `$cond`, which the engine rejects with `invalid argument: $cond`. The document is left untouched | exact |
+| guarded `$expr` atomic filters (`$add`, `$lte`, `$ifNull`) | exact on 10.6.0: the engine evaluates the client's fail-closed compilation (`$cond`, `$let`, `$isNumber`, `$type`), so the guard admits within the limit, refuses beyond it and never matches a stored value that is not a finite number. 8.0.2 rejects the compilation with `invalid argument: $cond` and leaves the document untouched | exact |
 | `watch()` change streams | unsupported. `NoSqlConnection` refuses with `unsupported_capability`, and so does a plain `SmartdataDb` whose engine identified itself; against an engine that answers no identity the refusal instead arrives from the engine as `CommandNotFound` once the change stream is read | supported on replica sets |
-| model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`; the engine cannot create one either and refuses the option itself with `InvalidOptions` (72) on both qualified releases. Migration-owned partial indexes stay reachable through `toleratedIndexNames` | not expressible, but a migration may own one |
+| model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`. A client decision, not an engine limit on every release — 10.6.0 creates partial indexes, 8.0.2 refuses the option with `InvalidOptions` (72) — because one model declaration has to hold on every qualified backend. A migration may create one on 10.6.0; `toleratedIndexNames` accepts it and inspection reports its filter | not expressible, but a migration may own one; inspection reports its filter |
 | aggregation-pipeline (array) updates | refused by the client with `invalid_argument` before any backend is contacted. A client-owned refusal, not an engine limit: both qualified engines apply a pipeline update themselves | same client refusal |
 
-`test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals row are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.5.0. The same boundary pins what 10.5.0 gained with it, a validated `$group` stage: a `$cond` inside a composite key and a non-document accumulator are refused with `TypeMismatch` (14) there, while 8.0.2 answers both. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.
+`test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals and guarded-`$expr` rows are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.6.0. The same boundary pins the rest of the engine's `$group` stage: a non-document accumulator is refused with `TypeMismatch` (14) on 10.6.0 while 8.0.2 answers it, and a `$cond` inside a composite key is evaluated per document on 10.6.0 while 8.0.2 answers its single literal row. It also pins whether a migration can create a partial index — 10.6.0 creates it and lists the filter, 8.0.2 refuses with 72. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.
 
 ## Relational SQL
 
@@ -197,14 +200,14 @@ Qualified engines:
 
 | Component | Qualified versions |
 | --- | --- |
-| NoSQLDB engine | **8.0.2 and 10.5.0** — the same `test/nosqldb/smartdb/` suite runs against both, through the single engine seam in `test/nosqldb/helpers/smartdb.ts`; `NOSQLDB_ENGINE=qualified` selects 10.5.0 |
+| NoSQLDB engine | **8.0.2 and 10.6.0** — the same `test/nosqldb/smartdb/` suite runs against both, through the single engine seam in `test/nosqldb/helpers/smartdb.ts`; `NOSQLDB_ENGINE=qualified` selects 10.6.0 |
 | MongoDB | 8.0.26 replica sets |
 | ObjectStorage | 10.1.0 |
 | SQLDB | 0.2.3 |
 | MariaDB | 11.8 |
 | ClickHouse | 25.8 |
 
-Both engine versions run the whole document suite. They part on one asserted boundary — 10.5.0 groups composite keys exactly and answers two-field grouped totals, 8.0.2 does neither and the client refuses there — which [Document APIs that need a MongoDB backend](#document-apis-that-need-a-mongodb-backend) states row by row. Text search, the Lucene adapter and the broad read-filter surface are exercised against MongoDB only. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
+Both engine versions run the whole document suite. They part on asserted boundaries — 10.6.0 groups composite keys exactly and answers two-field grouped totals, evaluates guarded `$expr` filters and creates migration-owned partial indexes, 8.0.2 does none of these and the client refuses the two-field form there — which [Document APIs that need a MongoDB backend](#document-apis-that-need-a-mongodb-backend) states row by row. Text search, the Lucene adapter and the broad read-filter surface are exercised against MongoDB only. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.5.0',
+  version: '1.6.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

package/ts/nosqldb/classes.collection.ts

@@ -39,6 +39,7 @@ import {
   getExpectedCollectionTopologyForSchema,
   getIdentityIndexName,
   isIdentityIndexFor,
+  isPlainIndexDocument,
   compareSmartdataTopologyStrings,
 } from './classes.collectiontopology.js';
 
@@ -210,6 +211,8 @@ export interface ISmartdataIndexInfo {
   unique: boolean;
   sparse: boolean;
   expireAfterSeconds?: number;
+  /** The filter of a partial index exactly as the backend lists it; absent otherwise. */
+  partialFilterExpression?: Record<string, unknown>;
 }
 interface ISmartdataDecoratorMetadata {
   globalSaveableProperties?: string[];
@@ -2814,6 +2817,9 @@ export class SmartdataCollection<T> {
           typeof indexArg.expireAfterSeconds === 'number'
             ? indexArg.expireAfterSeconds
             : undefined,
+        ...(isPlainIndexDocument(indexArg.partialFilterExpression)
+          ? { partialFilterExpression: indexArg.partialFilterExpression }
+          : {}),
       };
     });
   }

package/ts/nosqldb/classes.collectiontopology.ts

@@ -33,6 +33,13 @@ export interface ISmartdataCollectionTopologyIndex {
   readonly unique: boolean;
   readonly sparse: boolean;
   readonly expireAfterSeconds: number | null;
+  /**
+   * The filter of a partial index exactly as the backend lists it, present
+   * only on a partial index. Plain documents and arrays inside it are frozen
+   * copies; BSON values keep the type the driver decoded. A model never
+   * declares one, so an expected index never carries it.
+   */
+  readonly partialFilterExpression?: Readonly<Record<string, unknown>>;
 }
 
 export interface ISmartdataExpectedCollectionTopology {
@@ -110,6 +117,7 @@ const ordinaryActualIndexKeys = new Set([
   'unique',
   'sparse',
   'expireAfterSeconds',
+  'partialFilterExpression',
 ]);
 const textActualIndexKeys = new Set([
   ...ordinaryActualIndexKeys,
@@ -141,6 +149,37 @@ export const compareSmartdataTopologyStrings = (
   return leftCodePoints.length < rightCodePoints.length ? -1 : 1;
 };
 
+/** @internal Whether a listed index property is a plain BSON document. */
+export const isPlainIndexDocument = (
+  valueArg: unknown,
+): valueArg is Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null || Array.isArray(valueArg)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * Copies and freezes the documents and arrays of a listed index filter, so the
+ * reported filter is exactly what the backend listed and nobody can edit it
+ * afterwards. BSON values — ObjectIds, dates, decimals — are returned as the
+ * driver decoded them.
+ */
+const snapshotIndexFilterValue = (valueArg: unknown): unknown => {
+  if (Array.isArray(valueArg)) {
+    return Object.freeze(valueArg.map((entryArg) => snapshotIndexFilterValue(entryArg)));
+  }
+  if (isPlainIndexDocument(valueArg)) {
+    const copy: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(valueArg)) {
+      copy[key] = snapshotIndexFilterValue(entry);
+    }
+    return Object.freeze(copy);
+  }
+  return valueArg;
+};
+
 function freezeIndex(
   indexArg: {
     name: string;
@@ -152,6 +191,7 @@ function freezeIndex(
     unique: boolean;
     sparse: boolean;
     expireAfterSeconds: number | null;
+    partialFilterExpression?: Readonly<Record<string, unknown>>;
   },
 ): ISmartdataCollectionTopologyIndex {
   return Object.freeze({
@@ -162,6 +202,15 @@ function freezeIndex(
     unique: indexArg.unique,
     sparse: indexArg.sparse,
     expireAfterSeconds: indexArg.expireAfterSeconds,
+    // Absent rather than null on an ordinary index, so every index that is
+    // not partial reads exactly as it did before filters were reported.
+    ...(indexArg.partialFilterExpression === undefined
+      ? {}
+      : {
+          partialFilterExpression: snapshotIndexFilterValue(
+            indexArg.partialFilterExpression,
+          ) as Readonly<Record<string, unknown>>,
+        }),
   });
 }
 
@@ -390,6 +439,13 @@ const normalizeActualIndex = (
   if (rawIndex.sparse !== undefined && typeof rawIndex.sparse !== 'boolean') {
     supported = false;
   }
+  const partialFilterExpression = rawIndex.partialFilterExpression;
+  if (
+    partialFilterExpression !== undefined &&
+    !isPlainIndexDocument(partialFilterExpression)
+  ) {
+    supported = false;
+  }
   const expireAfterSeconds = rawIndex.expireAfterSeconds;
   if (
     expireAfterSeconds !== undefined &&
@@ -495,6 +551,9 @@ const normalizeActualIndex = (
       expireAfterSeconds >= 0
         ? expireAfterSeconds
         : null,
+    ...(isPlainIndexDocument(partialFilterExpression)
+      ? { partialFilterExpression }
+      : {}),
   });
   if (
     name === '_id_' &&
@@ -504,7 +563,8 @@ const normalizeActualIndex = (
     normalized.keys[0].weight === null &&
     (rawIndex.unique === undefined || rawIndex.unique === true) &&
     normalized.sparse === false &&
-    normalized.expireAfterSeconds === null
+    normalized.expireAfterSeconds === null &&
+    normalized.partialFilterExpression === undefined
   ) {
     normalized = fixedIdIndex;
   }

package/ts/nosqldb/classes.db.ts

@@ -37,6 +37,35 @@ import type { ICapabilities } from '../core/interfaces.js';
  */
 export type TConnectionStatus = 'initial' | 'disconnected' | 'connected' | 'failed';
 
+/**
+ * How a `SmartdataDb` connects. The first four fields locate and authenticate
+ * the database — the same shape as `IMongoDescriptor`, so every descriptor is
+ * valid options — and the pool fields tune the driver's connection pool.
+ */
+export interface ISmartdataDbOptions {
+  /**
+   * The connection URL. `<USERNAME>`/`<USER>`, `<PASSWORD>` and `<DBNAME>`
+   * (upper or lower case) are replaced with the URL-encoded `mongoDbUser`,
+   * `mongoDbPass` and `mongoDbName`.
+   */
+  mongoDbUrl: string;
+  /** The database to use. */
+  mongoDbName?: string;
+  mongoDbUser?: string;
+  mongoDbPass?: string;
+  /** Upper bound of pooled connections per server. Default 100. */
+  maxPoolSize?: number;
+  /** Milliseconds an idle pooled connection is kept before it is closed. Default 300000. */
+  maxIdleTimeMS?: number;
+  /**
+   * Milliseconds to wait for a suitable server. Default 30000. A bounded
+   * `init({ timeoutMs })` replaces it with the remaining init budget.
+   */
+  serverSelectionTimeoutMS?: number;
+  /** Milliseconds a socket may stay inactive before it is closed. Default 30000. */
+  socketTimeoutMS?: number;
+}
+
 export interface ISmartdataReadinessOptions {
   timeoutMs?: number;
   signal?: AbortSignal;
@@ -138,7 +167,7 @@ const assertExactDataObject = (
 };
 
 export class SmartdataDb {
-  smartdataOptions: plugins.tsclass.database.IMongoDescriptor;
+  smartdataOptions: ISmartdataDbOptions;
   mongoDbClient!: plugins.mongodb.MongoClient;
   mongoDb!: plugins.mongodb.Db;
   status: TConnectionStatus;
@@ -151,7 +180,7 @@ export class SmartdataDb {
   private engineIdentityState: ISmartdataEngineIdentity = unidentifiedSmartdataEngine;
   private capabilitiesState: ICapabilities | undefined;
 
-  constructor(smartdataOptions: plugins.tsclass.database.IMongoDescriptor) {
+  constructor(smartdataOptions: ISmartdataDbOptions) {
     this.smartdataOptions = smartdataOptions;
     this.status = 'initial';
     void this.statusConnectedDeferred.promise.catch(() => {});
@@ -219,9 +248,7 @@ export class SmartdataDb {
           .replace('<DBNAME>', this.smartdataOptions.mongoDbName || '')
           .replace('<dbname>', this.smartdataOptions.mongoDbName || '');
 
-        const descriptor = this.smartdataOptions as plugins.tsclass.database.IMongoDescriptor &
-          Pick<plugins.mongodb.MongoClientOptions, 'maxPoolSize' | 'maxIdleTimeMS' |
-            'serverSelectionTimeoutMS' | 'socketTimeoutMS'>;
+        const descriptor = this.smartdataOptions;
         const clientOptions: plugins.mongodb.MongoClientOptions = {
           maxPoolSize: descriptor.maxPoolSize ?? 100,
           maxIdleTimeMS: descriptor.maxIdleTimeMS ?? 300000,

package/ts/nosqldb/classes.doc.ts

@@ -5774,9 +5774,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   }
 
   /**
-   * saves this instance (optionally within a transaction)
+   * Saves this instance, optionally within a transaction. `session` takes the
+   * handle from `db.createSession()` — leased for the one write, like every
+   * other model API — or a raw driver session.
    */
-  public async save(opts?: { session?: plugins.mongodb.ClientSession }) {
+  public async save(opts?: { session?: TSmartdataOrdinarySession }) {
     if (getOrdinaryPersistencePolicy(this.constructor)) {
       throw new SmartdataPersistenceError('unsupported_operation',
         'Validated ordinary models use insert() or transactional postimage updates.');
@@ -5980,9 +5982,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   }
 
   /**
-   * deletes a document from the database (optionally within a transaction)
+   * Deletes this instance's document, optionally within a transaction.
+   * `session` takes the handle from `db.createSession()` — leased for the one
+   * write, like every other model API — or a raw driver session.
    */
-  public async delete(opts?: { session?: plugins.mongodb.ClientSession }) {
+  public async delete(opts?: { session?: TSmartdataOrdinarySession }) {
     const exactPersistencePolicy = (this.constructor as any)[
       exactPersistencePolicySymbol
     ] as { forbiddenDelete?: () => Promise<never> } | undefined;