@lossless.org/client 1.4.1 → 1.5.0

package/ts/nosqldb/classes.collection.ts

@@ -2369,8 +2369,7 @@ export class SmartdataCollection<T> {
     opts: (plugins.mongodb.ChangeStreamOptions & { bufferTimeMs?: number }) = {},
     smartdataDbDocArg?: typeof SmartDataDbDoc,
   ): Promise<SmartdataDbWatcher> {
-    if ('capabilities' in this.smartdataDb &&
-      (this.smartdataDb.capabilities as { changeStreams?: string }).changeStreams === 'unsupported') {
+    if (this.smartdataDb.capabilities?.changeStreams === 'unsupported') {
       throw new LosslessClientError('unsupported_capability', 'Change streams are unsupported by this backend.');
     }
     await this.init();

package/ts/nosqldb/classes.connection.ts

@@ -1,8 +1,14 @@
 import { SmartdataDb } from './classes.db.js';
+import {
+  composeSmartdataCapabilities,
+  smartdataCompositeGrouping,
+  type ISmartdataEngineIdentity,
+  type TSmartdataEngineBackend,
+} from './engineidentity.js';
 import type { ICapabilities, IOperationOptions, IReadiness } from '../core/interfaces.js';
 
 export interface INoSqlConnectionOptions {
-  backend: 'nosqldb' | 'mongodb';
+  backend: TSmartdataEngineBackend;
   url: string;
   database: string;
   username?: string;
@@ -11,17 +17,23 @@ export interface INoSqlConnectionOptions {
 }
 
 export class NoSqlConnection extends SmartdataDb {
-  public readonly backend: 'nosqldb' | 'mongodb';
-  public readonly capabilities: ICapabilities;
+  public readonly backend: TSmartdataEngineBackend;
+  private declaredCapabilities: ICapabilities;
+  /** A declared backend states its capabilities before the first connect. */
+  public override get capabilities(): ICapabilities { return this.declaredCapabilities; }
   constructor(public readonly options: INoSqlConnectionOptions) {
     super({ mongoDbUrl: options.url, mongoDbName: options.database,
       mongoDbUser: options.username, mongoDbPass: options.password,
       ...(options.connectionLimit === undefined ? {} : { maxPoolSize: options.connectionLimit }) });
     this.backend = options.backend;
-    this.capabilities = Object.freeze({ backend: options.backend,
-      transactions: options.backend === 'nosqldb' ? 'available' : 'unknown',
-      changeStreams: options.backend === 'nosqldb' ? 'unsupported' : 'unknown',
-      objectMetrics: 'unsupported', diskResidentScans: 'available' });
+    this.declaredCapabilities = composeSmartdataCapabilities(this.backend,
+      smartdataCompositeGrouping(this.engineIdentity));
+  }
+  /** The declared backend outranks the probe; only the probe knows the engine release. */
+  protected override applyEngineIdentity(identityArg: ISmartdataEngineIdentity): void {
+    super.applyEngineIdentity(identityArg);
+    this.declaredCapabilities = composeSmartdataCapabilities(this.backend,
+      smartdataCompositeGrouping(identityArg));
   }
   public async connect(options: IOperationOptions = {}): Promise<void> { await this.init(options); }
   public async ready(options: IOperationOptions = {}): Promise<IReadiness> {

package/ts/nosqldb/classes.db.ts

@@ -22,6 +22,15 @@ export type { TSmartdataOrdinarySession } from './classes.session.js';
 
 import { logger } from './logging.js';
 import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
+import {
+  composeSmartdataCapabilities,
+  probeSmartdataEngineIdentity,
+  smartdataCompositeGrouping,
+  smartdataEngineBackend,
+  unidentifiedSmartdataEngine,
+  type ISmartdataEngineIdentity,
+} from './engineidentity.js';
+import type { ICapabilities } from '../core/interfaces.js';
 
 /**
  * interface - indicates the connection status of the db
@@ -139,6 +148,8 @@ export class SmartdataDb {
   private lifecycleEpoch = 0;
   private activeLifecycleOperation: TSmartdataDbLifecycleOperation | null = null;
   private pendingClient?: plugins.mongodb.MongoClient;
+  private engineIdentityState: ISmartdataEngineIdentity = unidentifiedSmartdataEngine;
+  private capabilitiesState: ICapabilities | undefined;
 
   constructor(smartdataOptions: plugins.tsclass.database.IMongoDescriptor) {
     this.smartdataOptions = smartdataOptions;
@@ -146,6 +157,28 @@ export class SmartdataDb {
     void this.statusConnectedDeferred.promise.catch(() => {});
   }
 
+  /** What the last `init()` identified the connected engine as. */
+  public get engineIdentity(): ISmartdataEngineIdentity {
+    return this.engineIdentityState;
+  }
+
+  /**
+   * What the identified engine can do, or `undefined` while no engine is
+   * identified. A caller must read the absent statement as "not available".
+   */
+  public get capabilities(): ICapabilities | undefined {
+    return this.capabilitiesState;
+  }
+
+  /** Records the identity `init()` read and restates the capabilities it implies. */
+  protected applyEngineIdentity(identityArg: ISmartdataEngineIdentity): void {
+    this.engineIdentityState = identityArg;
+    const backend = smartdataEngineBackend(identityArg);
+    this.capabilitiesState = backend === undefined
+      ? undefined
+      : composeSmartdataCapabilities(backend, smartdataCompositeGrouping(identityArg));
+  }
+
   // easystore
   public async createEasyStore<T = unknown>(nameIdArg: string): Promise<EasyStore<T>> {
     const easyStore = new EasyStore<T>(nameIdArg, this);
@@ -224,6 +257,11 @@ export class SmartdataDb {
           collection.resetForDatabaseReconnect();
         }
         budget?.check();
+        // The engine is asked what it is before the connection is published, so
+        // no operation can run against a database whose capabilities are stale.
+        this.applyEngineIdentity(await probeSmartdataEngineIdentity(candidateDb, budget));
+        // The probe absorbs its own failures, so a budget that expired during it must still refuse here.
+        budget?.check();
         this.mongoDbClient = candidateClient;
         this.mongoDb = candidateDb;
         candidateClient = undefined;

package/ts/nosqldb/classes.doc.ts

@@ -5001,6 +5001,20 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       120_000,
     );
     const timeoutMS = requireBoundedInteger(timeoutMSOption, 'Grouped totals timeoutMS', 120_000);
+    const collection: SmartdataCollection<T> = (this as any).collection;
+    if (
+      groupByFields.length === 2
+      && collection.smartdataDb.capabilities?.compositeGrouping !== 'exact'
+    ) {
+      // The backend would answer a composite group key without evaluating it,
+      // and a wrong total that never raises is worse than no total at all.
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        `Grouped totals cannot group by "${groupByFields[0]}" and "${groupByFields[1]}" together: `
+        + 'this backend does not evaluate a composite group key exactly. Group by one field per '
+        + `call, such as groupBy: ["${groupByFields[0]}"].`,
+      );
+    }
     const groupStage: Record<string, unknown> = {
       _id: groupByFields.length === 1
         ? '$' + groupByFields[0]
@@ -5012,7 +5026,6 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     for (const [index, sumField] of sumFields.entries()) {
       groupStage['__groupedTotalsSum' + index] = { $sum: '$' + sumField };
     }
-    const collection: SmartdataCollection<T> = (this as any).collection;
     const rows = await collection.aggregateGroupedTotals(
       filterOption !== undefined
         ? (this as any).normalizeReadFilter(filterOption)

package/ts/nosqldb/classes.easystore.ts

@@ -50,6 +50,22 @@ export class EasyStore<T> {
     this.easyStoreClass = getEasyStoreClassForDb<T>(smartdataDbRefArg);
   }
 
+  /**
+   * Installs the store's declared `nameId` index before any caller opens a
+   * transaction, and resolves once the collection is initialized. Idempotent:
+   * every call after the first returns without touching the backend.
+   *
+   * A model's declared indexes are created on the first model-API touch of its
+   * collection, as unsessioned DDL. While a transaction holds that collection
+   * the DDL waits for it, so a first `readKey()`/`writeKey()` raced against a
+   * transaction stalls until the client deadline instead of answering. A
+   * consumer that opens transactions on the same database calls this once
+   * during startup, before the store is read or written.
+   */
+  public async ensureInitialized(): Promise<void> {
+    await (this.easyStoreClass as typeof SmartDataDbDoc).ensureInitialized();
+  }
+
   private easyStorePromise?: Promise<InstanceType<typeof this.easyStoreClass>>;
   private async getEasyStore(): Promise<InstanceType<typeof this.easyStoreClass>> {
     if (this.easyStorePromise) {

package/ts/nosqldb/engineidentity.ts

@@ -0,0 +1,153 @@
+import * as plugins from './plugins.js';
+import type { SmartdataOperationBudget } from './classes.operationbudget.js';
+import type { ICapabilities, TCompositeGrouping } from '../core/interfaces.js';
+
+/**
+ * What the connected engine states it is. `unknown` is the fail-closed answer:
+ * the engine either does not implement the identity probe or does not answer it
+ * in a shape that identifies anything.
+ */
+export type TSmartdataEngineProduct = 'NoSQLDB' | 'MongoDB' | 'unknown';
+
+/** The document backend a connection is actually talking to. */
+export type TSmartdataEngineBackend = 'nosqldb' | 'mongodb';
+
+export interface ISmartdataEngineIdentity {
+  readonly product: TSmartdataEngineProduct;
+  /**
+   * The engine's own version — NoSQLDB's released package version, MongoDB's
+   * server version — or `null` when the engine states none.
+   */
+  readonly version: string | null;
+}
+
+export const unidentifiedSmartdataEngine: ISmartdataEngineIdentity = Object.freeze({
+  product: 'unknown',
+  version: null,
+});
+
+/**
+ * The NoSQLDB release that evaluates a composite `$group` key instead of
+ * answering with the literal field paths: @lossless.org/nosqldb 10.5.0.
+ */
+const compositeGroupingEngineRelease = '10.5.0';
+
+const parseEngineVersion = (versionArg: string): readonly number[] | undefined => {
+  const parts = versionArg.split('.');
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  const numbers = parts.map((partArg) =>
+    /^\d+$/.test(partArg) ? Number(partArg) : Number.NaN,
+  );
+  return numbers.some((numberArg) => !Number.isSafeInteger(numberArg)) ? undefined : numbers;
+};
+
+/**
+ * Compares two release versions. A version this cannot parse — a prerelease or
+ * any other shape — counts as below the minimum, so an engine only ever gains a
+ * capability by stating a release that plainly carries it.
+ */
+const engineVersionReaches = (versionArg: string, minimumArg: string): boolean => {
+  const version = parseEngineVersion(versionArg);
+  const minimum = parseEngineVersion(minimumArg);
+  if (version === undefined || minimum === undefined) {
+    return false;
+  }
+  for (const [index, minimumPart] of minimum.entries()) {
+    if (version[index] !== minimumPart) {
+      return version[index] > minimumPart;
+    }
+  }
+  return true;
+};
+
+export const smartdataEngineBackend = (
+  identityArg: ISmartdataEngineIdentity,
+): TSmartdataEngineBackend | undefined => {
+  switch (identityArg.product) {
+    case 'NoSQLDB':
+      return 'nosqldb';
+    case 'MongoDB':
+      return 'mongodb';
+    case 'unknown':
+      return undefined;
+  }
+};
+
+export const smartdataCompositeGrouping = (
+  identityArg: ISmartdataEngineIdentity,
+): TCompositeGrouping => {
+  switch (identityArg.product) {
+    case 'MongoDB':
+      return 'exact';
+    case 'NoSQLDB':
+      return identityArg.version !== null
+        && engineVersionReaches(identityArg.version, compositeGroupingEngineRelease)
+        ? 'exact'
+        : 'unsupported';
+    case 'unknown':
+      return 'unsupported';
+  }
+};
+
+export const composeSmartdataCapabilities = (
+  backendArg: TSmartdataEngineBackend,
+  compositeGroupingArg: TCompositeGrouping,
+): ICapabilities => {
+  const capabilities: ICapabilities = {
+    backend: backendArg,
+    transactions: backendArg === 'nosqldb' ? 'available' : 'unknown',
+    changeStreams: backendArg === 'nosqldb' ? 'unsupported' : 'unknown',
+    compositeGrouping: compositeGroupingArg,
+    objectMetrics: 'unsupported',
+    diskResidentScans: 'available',
+  };
+  return Object.freeze(capabilities);
+};
+
+const isDocumentRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const readSmartdataEngineIdentity = (
+  answerArg: plugins.mongodb.Document,
+): ISmartdataEngineIdentity => {
+  const vendorDocument: unknown = answerArg.nosqldb;
+  if (vendorDocument === undefined) {
+    // No vendor document: a MongoDB `buildInfo`, whose `version` is the server's own.
+    const version: unknown = answerArg.version;
+    return Object.freeze({
+      product: 'MongoDB',
+      version: typeof version === 'string' ? version : null,
+    });
+  }
+  if (
+    isDocumentRecord(vendorDocument)
+    && vendorDocument.product === 'NoSQLDB'
+    && typeof vendorDocument.version === 'string'
+  ) {
+    return Object.freeze({ product: 'NoSQLDB', version: vendorDocument.version });
+  }
+  // A vendor document that states no product and version identifies nothing.
+  return unidentifiedSmartdataEngine;
+};
+
+/**
+ * Asks the connected engine what it is with one `buildInfo` command. NoSQLDB
+ * answers it pre-authentication and from build metadata alone; MongoDB answers
+ * it for every connection. An engine that refuses the command — NoSQLDB 8.0.2
+ * answers `CommandNotFound` (59) — stays unidentified, and an unidentified
+ * engine never enables a capability.
+ */
+export const probeSmartdataEngineIdentity = async (
+  dbArg: plugins.mongodb.Db,
+  budgetArg?: SmartdataOperationBudget,
+): Promise<ISmartdataEngineIdentity> => {
+  try {
+    return readSmartdataEngineIdentity(
+      await dbArg.command({ buildInfo: 1 }, budgetArg?.operationOptions()),
+    );
+  } catch {
+    return unidentifiedSmartdataEngine;
+  }
+};

package/ts/nosqldb/index.ts

@@ -3,6 +3,17 @@ import './shim.js';
 
 export { NoSqlConnection } from './classes.connection.js';
 export type { INoSqlConnectionOptions } from './classes.connection.js';
+export type {
+  ISmartdataEngineIdentity,
+  TSmartdataEngineBackend,
+  TSmartdataEngineProduct,
+} from './engineidentity.js';
+export type {
+  ICapabilities,
+  TBackend,
+  TCapability,
+  TCompositeGrouping,
+} from '../core/interfaces.js';
 export { nosqldbLineage } from './lineage.js';
 export type { INosqldbLineage } from './lineage.js';
 

package/ts/nosqldb/lineage.ts

@@ -20,6 +20,8 @@ export const nosqldbLineage: INosqldbLineage = Object.freeze({
     'classes.connection.ts adds NoSqlConnection with the client backend, capability and readiness contract.',
     'index.ts exports NoSqlConnection, INoSqlConnectionOptions and this lineage constant.',
     'classes.collection.ts refuses watch() when the connected backend reports change streams as unsupported.',
+    'classes.db.ts identifies the engine at init() and states the capabilities that identity implies.',
+    'classes.doc.ts refuses two-field grouped totals on a backend that does not group composite keys exactly.',
     'The package version file is dropped; versioning belongs to @lossless.org/client.',
   ]),
 });

package/ts/objectstorage/classes.connection.ts

@@ -26,7 +26,7 @@ export class ObjectStorageConnection extends SmartBucket {
       { forcePathStyle: options.forcePathStyle });
     this.backend = options.backend;
     this.capabilities = Object.freeze({ backend: this.backend, transactions: 'unsupported', changeStreams: 'unsupported',
-      objectMetrics: 'unsupported', diskResidentScans: 'unknown' });
+      compositeGrouping: 'unsupported', objectMetrics: 'unsupported', diskResidentScans: 'unknown' });
   }
   public async ready(options: IOperationOptions = {}): Promise<IReadiness> {
     if (!this.options.readinessBucket) return { ready: false, reason: 'readiness_bucket_required' };

package/ts/sqldb/classes.clickhouseconnection.ts

@@ -11,7 +11,8 @@ export class ClickHouseConnection {
   public readonly backend = 'clickhouse' as const;
   public readonly metrics: SmartClickHouseDb;
   public readonly capabilities: ICapabilities = Object.freeze({ backend: 'clickhouse',
-    transactions: 'unsupported', changeStreams: 'unsupported', objectMetrics: 'unsupported', diskResidentScans: 'available' });
+    transactions: 'unsupported', changeStreams: 'unsupported', compositeGrouping: 'unsupported',
+    objectMetrics: 'unsupported', diskResidentScans: 'available' });
   private client?: plugins.clickhouse.ClickHouseClient;
   private readonly operations = new Map<Operation, () => void>();
   private readonly tasks = new Set<Promise<unknown>>();

package/ts/sqldb/classes.sqlconnection.ts

@@ -83,7 +83,7 @@ export class SqlConnection {
     }
     this.backend = options.backend;
     this.capabilities = Object.freeze({ backend: this.backend, transactions: 'available',
-      changeStreams: 'unsupported', objectMetrics: 'unsupported',
+      changeStreams: 'unsupported', compositeGrouping: 'unsupported', objectMetrics: 'unsupported',
       diskResidentScans: this.backend === 'sqldb' ? 'unsupported' : 'available' });
   }