@lossless.org/client 1.17.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "private": false,
   "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
   "exports": {
@@ -46,12 +46,11 @@
   "homepage": "https://code.foss.global/lossless.org/client#readme",
   "dependencies": {
     "@push.rocks/lik": "^6.4.0",
-    "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartlog": "^3.2.1 || ^4.0.0",
     "@push.rocks/smartmime": "^2.0.4",
     "@push.rocks/smartobject": "^1.0.12",
     "@push.rocks/smartpath": "^6.0.0",
-    "@push.rocks/smartpromise": "^4.2.5",
+    "@push.rocks/smartpromise": "^4.3.0",
     "@push.rocks/smartrx": "^3.0.10",
     "@push.rocks/smartstream": "^3.4.0",
     "@push.rocks/smartstring": "^4.1.0",
@@ -81,10 +80,10 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.1039.0",
     "@clickhouse/client": "1.23.1",
-    "@git.zone/tsbuild": "5.0.0",
-    "@git.zone/tsbundle": "3.1.0",
+    "@git.zone/tsbuild": "5.1.2",
+    "@git.zone/tsbundle": "3.1.2",
     "@git.zone/tsrun": "3.0.2",
-    "@git.zone/tstest": "6.3.2",
+    "@git.zone/tstest": "6.3.4",
     "@lossless.org/nosqldb": "8.0.2",
     "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.7.2",
     "@lossless.org/objectstorage": "10.3.1",

package/readme.md

@@ -114,6 +114,7 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Grouped totals element filter | `elementFilter: { 'lines.accountNumber': '1200' }` beside `unwind: 'lines'` counts and sums only the matching elements — one account's balance per side — with the atomic-filter operators on the unwound array and its declared element paths; any other path or operator is refused with `invalid_argument` |
 | Grouped totals paging | rows come ordered by group key; `getGroupedTotalsPage()` returns `nextCursor` while `hasMore`, `cursor` continues after it, and `iterateGroupedTotals()` reads every group page by page — exact across pages for null, number, string and boolean group values (proven on NoSQLDB 8.0.2, 10.7.2 and MongoDB; ObjectId and date values are ordered by BSON type order but not yet covered by the paging tests), refused with `unsupported_operation` for other values, and a cursor from another query is refused with `invalid_argument` |
 | Query-plan inspection | `Model.inspectQueryPlan(db, { filter, sort?, projection?, limit?, timeoutMS?, signal? })` — the winning plan's stages (`stage`, `depth`, `indexName`, `direction`) and `nReturned`/`totalKeysExamined`/`totalDocsExamined`, read-only and bounded, so a consumer proves a model query uses its intended index without raw driver access |
+| Per-instance model binding | `bindDocToManager(manager, Model)` returns a subclass of a model declared with `@managed()` and no manager argument, named like the model and bound to that manager, so several databases use the same models at once; any other binding is refused with `invalid_configuration` |
 | Disposable test databases on a unix socket | `SmartdataTestDatabase.create({ connection: { socketPath } })` from `@lossless.org/client/testsupport` reaches an engine that listens only on a unix-domain socket, fault helpers included; the loopback `host`/`port` form is unchanged |
 
 `docs/source/smartdata/readme.md` documents each one with its refusals.

package/ts/00_commitinfo_data.ts

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

package/ts/nosqldb/classes.collection.ts

@@ -37,6 +37,7 @@ import {
 import {
   collectionModelSchemaResolverSymbol,
   collectionTopologyDbInspectionSymbol,
+  findCollectionModelSchemaResolver,
   getExpectedCollectionTopologyForSchema,
   getIdentityIndexName,
   isIdentityIndexFor,
@@ -1219,12 +1220,23 @@ export const getIdentityDocumentIdField = (modelArg: any): string | undefined =>
     : undefined;
 };
 
+/**
+ * Records on every collection binding whether its database follows the
+ * receiver's manager. Only such a binding can be bound per instance through
+ * `bindDocToManager()`; a binding with a fixed database or manager would
+ * silently keep using it.
+ */
+const managerFollowsReceiverSymbol = Symbol(
+  '@lossless.org/client.nosqldb.managerFollowsReceiver',
+);
+
 const installCollectionBinding = <
   TModel extends SmartDataDbDoc<any, any>,
 >(
   constructorArg: TCollectionModelConstructor<TModel>,
   dbResolverArg: (receiverArg?: unknown) => SmartdataDb,
   schemaResolverArg: () => INormalizedCollectionModelSchema,
+  managerFollowsReceiverArg = false,
 ): TCollectionModelConstructor<TModel> => {
   const getCollection = (receiverArg?: unknown) => {
     const db = dbResolverArg(receiverArg);
@@ -1251,6 +1263,12 @@ const installCollectionBinding = <
     configurable: true,
     writable: false,
   });
+  Object.defineProperty(constructorArg, managerFollowsReceiverSymbol, {
+    value: managerFollowsReceiverArg,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  });
   (constructorArg as any).className = constructorArg.name;
   Object.defineProperty(constructorArg, 'collection', {
     get(this: unknown) {
@@ -1620,6 +1638,58 @@ export const setDefaultManagerForDoc = <T,>(managerArg: IManager, dbDocArg: T):
   return dbDocArg;
 };
 
+/**
+ * Returns a subclass of a `@managed()` model that is bound to `managerArg`.
+ *
+ * `setDefaultManagerForDoc()` sets the manager on the model itself, so every
+ * binding of one model shares the manager set last. The bound subclass carries
+ * its own manager instead: an application instance binds every model it uses,
+ * and several instances run on several databases at once. The subclass keeps
+ * the model's name, collection and declarations, and its statics and instances
+ * use the manager's `db` whenever they reach the database, so the manager may
+ * connect after binding. The binding is fixed for the subclass's lifetime.
+ *
+ * The model must be declared with `@managed()` without a manager argument;
+ * any other binding would ignore the bound manager, and a subclass that
+ * declares fields or a policy without a declaration of its own has no schema.
+ * Both are refused with `invalid_configuration`.
+ */
+export const bindDocToManager = <
+  TDoc extends abstract new (...args: never[]) => object,
+>(
+  managerArg: IManager,
+  docArg: TDoc,
+): TDoc => {
+  if (
+    typeof docArg !== 'function' ||
+    !(docArg.prototype instanceof SmartDataDbDoc) ||
+    (docArg as unknown as Record<symbol, unknown>)[managerFollowsReceiverSymbol] !== true ||
+    findCollectionModelSchemaResolver(docArg) === undefined
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Model "${typeof docArg === 'function' ? docArg.name : 'unknown'}" cannot be bound to a manager; ` +
+        'declare it with @managed() without a manager argument.',
+    );
+  }
+  if (typeof managerArg !== 'object' || managerArg === null) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Model "${docArg.name}" can only be bound to a manager object.`,
+    );
+  }
+  const modelConstructor = docArg as unknown as new () => SmartDataDbDoc<object, object>;
+  const boundDoc = class extends modelConstructor {};
+  Object.defineProperty(boundDoc, 'name', { value: docArg.name, configurable: true });
+  Object.defineProperty(boundDoc.prototype, 'defaultManager', {
+    value: managerArg,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return boundDoc as unknown as TDoc;
+};
+
 /**
  * This is a decorator that will tell the decorated class what dbTable to use
  * @param dbArg
@@ -1682,6 +1752,7 @@ export function managed<TManager extends IManager>(
           bindingOptions?.toleratedIndexNames,
         );
       },
+      !managerArg,
     );
     Object.defineProperty(constructor, 'manager', {
       get(this: unknown) { return getManager(this); },

package/ts/nosqldb/classes.collectiontopology.ts

@@ -2,6 +2,7 @@ import type * as plugins from './plugins.js';
 import type { INormalizedCollectionModelSchema } from './classes.collection.js';
 import type { SmartdataDb } from './classes.db.js';
 import { SmartdataPersistenceError } from './classes.persistence.js';
+import { resolvesSamePersistencePolicies } from './classes.ordinarypersistence.js';
 
 export type TSmartdataCollectionTopologyStatus =
   | 'absent'
@@ -228,18 +229,44 @@ const indexValuesEqual = (
   rightArg: ISmartdataCollectionTopologyIndex,
 ): boolean => JSON.stringify(leftArg) === JSON.stringify(rightArg);
 
+const decoratorMetadataSymbol = (Symbol as unknown as { readonly metadata: symbol }).metadata;
+
+/**
+ * @internal Finds the collection schema binding a model resolves: its own, or
+ * the one of the model it extends when it declares nothing of its own. Such an
+ * undecorated subclass — `bindDocToManager()` creates one per manager — is
+ * described exactly by the inherited schema. A subclass that declares decorator
+ * metadata or a persistence policy without a binding of its own is not, so it
+ * resolves none.
+ */
+export const findCollectionModelSchemaResolver = (
+  constructorArg: unknown,
+): TCollectionModelSchemaResolver | undefined => {
+  if (typeof constructorArg !== 'function') {
+    return undefined;
+  }
+  let owner: unknown = constructorArg;
+  while (typeof owner === 'function') {
+    if (Object.hasOwn(owner, collectionModelSchemaResolverSymbol)) {
+      const resolver = (owner as ICollectionTopologyModelConstructor)[collectionModelSchemaResolverSymbol];
+      return typeof resolver === 'function' &&
+        resolvesSamePersistencePolicies(constructorArg, owner)
+        ? resolver
+        : undefined;
+    }
+    if (Object.hasOwn(owner, decoratorMetadataSymbol)) {
+      return undefined;
+    }
+    owner = Object.getPrototypeOf(owner);
+  }
+  return undefined;
+};
+
 const getSchemaResolver = (
   constructorArg: ICollectionTopologyModelConstructor,
 ): TCollectionModelSchemaResolver => {
-  const resolver = constructorArg?.[collectionModelSchemaResolverSymbol];
-  if (
-    typeof constructorArg !== 'function' ||
-    !Object.prototype.hasOwnProperty.call(
-      constructorArg,
-      collectionModelSchemaResolverSymbol,
-    ) ||
-    typeof resolver !== 'function'
-  ) {
+  const resolver = findCollectionModelSchemaResolver(constructorArg);
+  if (resolver === undefined) {
     throw new SmartdataPersistenceError(
       'invalid_configuration',
       `Model "${constructorArg?.name || 'unknown'}" has no collection schema binding.`,

package/ts/nosqldb/classes.distributedcoordinator.ts

@@ -77,7 +77,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
   private startHeartbeat = async () => {
     while (this.ownInstance.data.status !== 'stopped') {
       await this.sendHeartbeat();
-      await plugins.smartdelay.delayForRandom(5000, 10000);
+      await plugins.smartpromise.delayForRandom(5000, 10000);
     }
   };
 
@@ -179,7 +179,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
         logger.log('info', 'bidding code stored.');
       });
       logger.log('info', `bidding for leadership...`);
-      await plugins.smartdelay.delayFor(plugins.smarttime.getMilliSecondsFromUnits({ seconds: 5 }));
+      await plugins.smartpromise.delayFor(plugins.smarttime.getMilliSecondsFromUnits({ seconds: 5 }));
       await this.asyncExecutionStack.getExclusiveExecutionSlot(async () => {
         let biddingInstances = await DistributedClass.getInstances({});
         biddingInstances = biddingInstances.filter(
@@ -195,7 +195,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
             this.ownInstance.data.elected = false;
           }
         }
-        await plugins.smartdelay.delayFor(5000);
+        await plugins.smartpromise.delayFor(5000);
         logger.log('info', `settling with status elected = ${this.ownInstance.data.elected}`);
         this.ownInstance.data.status = 'settled';
         await this.ownInstance.save();
@@ -221,7 +221,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
        * all instances that requested this task
        */
       requestingDistibutedInstanceIds: string[];
-      responseTimeout: plugins.smartdelay.Timeout<any>;
+      responseTimeout: plugins.smartpromise.Timeout<any>;
     }> = [];
 
     this.distributedWatcher.changeSubject.subscribe({
@@ -243,7 +243,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
           await instance.delete();
         }
       }
-      await plugins.smartdelay.delayFor(10000);
+      await plugins.smartpromise.delayFor(10000);
     }
   }
 
@@ -260,7 +260,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
       this.ownInstance.data.taskRequests.push(taskRequestArg);
       await this.ownInstance.save();
     });
-    await plugins.smartdelay.delayFor(10000);
+    await plugins.smartpromise.delayFor(10000);
     const result = await this.asyncExecutionStack.getExclusiveExecutionSlot(async () => {
       await this.ownInstance.updateFromDb();
       const taskRequestResult = this.ownInstance.data.taskRequestResults.find((resultItem) => {
@@ -291,7 +291,7 @@ export class SmartdataDistributedCoordinator extends plugins.taskbuffer.distribu
       }
       Object.assign(existingInfoBasis, infoBasisArg);
       await this.ownInstance.save();
-      plugins.smartdelay.delayFor(60000).then(() => {
+      plugins.smartpromise.delayFor(60000).then(() => {
         this.asyncExecutionStack.getExclusiveExecutionSlot(async () => {
           const indexToRemove = this.ownInstance.data.taskRequests.indexOf(existingInfoBasis);
           if (indexToRemove >= 0) {

package/ts/nosqldb/classes.easystore.ts

@@ -246,7 +246,7 @@ export class EasyStore<T> {
   public async cleanUpEphemeral() {
     // Clean up ephemeral data periodically while connected
     while (this.smartdataDbRef.status === 'connected') {
-      await plugins.smartdelay.delayFor(60000); // Check every minute
+      await plugins.smartpromise.delayFor(60000); // Check every minute
       // TODO: Implement actual cleanup logic for ephemeral data
       // For now, this prevents the infinite CPU loop
     }

package/ts/nosqldb/classes.ordinarypersistence.ts

@@ -28,6 +28,14 @@ const exactSymbol = Symbol.for('@push.rocks/smartdata.exactPersistencePolicy');
 export const hasExactPersistencePolicy = (modelArg: any): boolean =>
   Boolean(modelArg?.[exactSymbol]);
 
+/**
+ * @internal Whether two models resolve the same ordinary and exact persistence
+ * policies, so one model's collection schema describes the other.
+ */
+export const resolvesSamePersistencePolicies = (leftArg: object, rightArg: object): boolean =>
+  Reflect.get(leftArg, policySymbol) === Reflect.get(rightArg, policySymbol) &&
+  Reflect.get(leftArg, exactSymbol) === Reflect.get(rightArg, exactSymbol);
+
 export const getOrdinaryPersistencePolicy = (modelArg: any): IOrdinaryPersistencePolicy | undefined => {
   const policy = modelArg?.[policySymbol] as IOrdinaryPersistencePolicy | undefined;
   if (policy && modelArg[exactSymbol]) {

package/ts/nosqldb/classes.watcher.ts

@@ -67,7 +67,7 @@ export class SmartdataDbWatcher<T = any> extends EventEmitter {
     this.changeStream.on('change', this.onChange);
     this.changeStream.on('error', this.onStreamError);
     // Signal readiness after one tick
-    plugins.smartdelay.delayFor(0).then(() => {
+    plugins.smartpromise.delayFor(0).then(() => {
       this.readyDeferred.resolve();
     });
   }

package/ts/nosqldb/plugins.ts

@@ -5,7 +5,6 @@ export { tsclass };
 
 // @pushrocks scope
 import * as lik from '@push.rocks/lik';
-import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartlog from '@push.rocks/smartlog';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrx from '@push.rocks/smartrx';
@@ -21,7 +20,6 @@ import * as nodeNet from 'node:net';
 
 export {
   lik,
-  smartdelay,
   smartpromise,
   smartlog,
   smartrx,

package/ts/sqldb/clickhouse/smartclickhouse.classes.clickhousetable.ts

@@ -301,7 +301,7 @@ export class ClickhouseTable<T extends Record<string, any>> {
           'SELECT count() AS cnt FROM system.mutations WHERE is_done = 0 AND database = {database:String} AND table = {table:String}',
           { database: this.options.database, table: this.options.tableName }, { signal: operation.signal });
         if (BigInt(rows[0]?.cnt ?? 0) === 0n) return;
-        await plugins.smartdelay.delayFor(100);
+        await plugins.smartpromise.delayFor(100);
       }
     } finally { operation.dispose(); }
   }

package/ts/sqldb/clickhouse/smartclickhouse.classes.smartclickhouse.ts

@@ -83,7 +83,7 @@ export class SmartClickHouseDb {
       while (true) {
         operation.check();
         if (await this.clickhouseHttpClient.ping({ signal: operation.signal })) return;
-        await plugins.smartdelay.delayFor(100, null, this.options.unref);
+        await plugins.smartpromise.delayFor(100, null, this.options.unref);
       }
     } finally { operation.dispose(); }
   }

package/ts/sqldb/clickhouse/smartclickhouse.plugins.ts

@@ -1,5 +1,4 @@
-import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartobject from '@push.rocks/smartobject';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrx from '@push.rocks/smartrx';
-export { smartdelay, smartobject, smartpromise, smartrx };
+export { smartobject, smartpromise, smartrx };