@lossless.org/client 0.1.1 → 1.1.0

package/ts/nosqldb/classes.atomicupdate.ts

@@ -52,6 +52,73 @@ export const executeAtomicUpdate = async <T>(
   );
 };
 
+/**
+ * Executes a bounded batch of model-validated atomic upserts against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpsertMany()` owns the
+ * public API and must validate and normalize every filter and update before
+ * calling this raw persistence boundary. Each entry applies atomically; the
+ * batch as a whole is not isolated unless the caller supplies a transaction
+ * session.
+ */
+export const executeAtomicUpsertMany = async <T>(
+  collectionArg: SmartdataCollection<T>,
+  operationsArg: ReadonlyArray<{
+    filter: plugins.mongodb.Filter<plugins.mongodb.Document>;
+    update: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>;
+  }>,
+  optsArg?: {
+    session?: TSmartdataOrdinarySession;
+    timeoutMS?: number;
+  },
+): Promise<{
+  acknowledged: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+  upsertedCount: number;
+}> => {
+  return runWithOrdinarySmartdataSession(
+    optsArg?.session,
+    collectionArg.smartdataDb,
+    {
+      ordinaryWrite: true,
+      prepared: collectionArg.isInitializedForCurrentDatabase(),
+      preparationMessage:
+        `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    },
+    async (rawSessionArg) => {
+      await collectionArg.init();
+      try {
+        const result = await collectionArg.mongoDbCollection.bulkWrite(
+          operationsArg.map((operationArg) => ({
+            updateOne: {
+              filter: operationArg.filter,
+              update: operationArg.update,
+              upsert: true,
+            },
+          })),
+          {
+            ordered: false,
+            session: rawSessionArg,
+            timeoutMS: optsArg?.timeoutMS,
+          },
+        );
+        return {
+          acknowledged: result.isOk(),
+          matchedCount: result.matchedCount,
+          modifiedCount: result.modifiedCount,
+          upsertedCount: result.upsertedCount,
+        };
+      } catch (errorArg) {
+        return normalizeOrdinaryPersistenceError(
+          errorArg,
+          `Atomic upsert-many conflicts with a unique index in collection "${collectionArg.collectionName}".`,
+        );
+      }
+    },
+  );
+};
+
 /**
  * Executes a model-validated atomic update-many against MongoDB.
  *

package/ts/nosqldb/classes.collection.ts

@@ -6,7 +6,8 @@ import {
   type ISmartdataCollectionPreparationOptions,
 } from './classes.collectionpreparation.js';
 import {
-  getOrdinaryPersistencePolicy, validateOrdinaryStoredDocument,
+  getOrdinaryPersistencePolicy, hasExactPersistencePolicy,
+  validateOrdinaryStoredDocument,
   type IOrdinaryPersistencePolicy,
 } from './classes.ordinarypersistence.js';
 import { SmartdataDb } from './classes.db.js';
@@ -57,6 +58,14 @@ export interface ICollectionBindingOptions {
    * its legacy collection without changing stored data.
    */
   collectionName?: string;
+  /**
+   * Stores one declared `@unI()` string identity as the document `_id`, making
+   * the primary key itself the uniqueness authority. The field keeps its own
+   * stored value and receives no separate unique index. Irreversible for an
+   * existing collection: every stored document must already satisfy
+   * `_id === document[field]`.
+   */
+  identityAsDocumentId?: string;
 }
 
 export type TCollectionModelIndexDirection = 1 | -1 | 'text';
@@ -106,6 +115,13 @@ export interface ICollectionModelConfig<TModel extends object = any> {
    * ascending unique index in `indexes`.
    */
   identityFields?: ReadonlyArray<TStringFieldKey<TModel>>;
+  /**
+   * Stores one declared string identity as the document `_id`. The primary key
+   * becomes the uniqueness authority, so the field must not declare its own
+   * unique index. Irreversible for an existing collection: every stored
+   * document must already satisfy `_id === document[field]`.
+   */
+  identityAsDocumentId?: TStringFieldKey<TModel>;
   /**
    * Persisted fields used by SmartData's search helpers.
    */
@@ -122,6 +138,8 @@ export interface INormalizedCollectionModelSchema {
   readonly persistedFields: readonly string[];
   readonly numericFields: readonly string[];
   readonly identityFields: readonly string[];
+  /** Declared identity field stored as the document `_id`, if any. */
+  readonly identityAsDocumentId?: string;
   readonly identityValueTypes: Readonly<
     Record<string, TSmartdataIdentityValueType>
   >;
@@ -323,6 +341,7 @@ const normalizeCollectionModelSchema = (
     'persistedFields',
     'numericFields',
     'identityFields',
+    'identityAsDocumentId',
     'searchableFields',
     'indexes',
   ]);
@@ -395,6 +414,24 @@ const normalizeCollectionModelSchema = (
       identityFields.push(field);
     }
   }
+  const identityAsDocumentId = configArg.identityAsDocumentId;
+  if (identityAsDocumentId !== undefined) {
+    if (
+      typeof identityAsDocumentId !== 'string' ||
+      !identityFields.includes(identityAsDocumentId)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Collection model identityAsDocumentId must name a declared identity field.',
+      );
+    }
+    if (ordinaryPolicyArg?.idType === 'string') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${identityAsDocumentId}" cannot own the document _id together with a string ordinary persistence _id.`,
+      );
+    }
+  }
   const identityValueTypes: Record<string, TSmartdataIdentityValueType> = {};
   for (const field of Object.keys(identityValueTypesArg || {})) {
     if (!identityFields.includes(field)) {
@@ -564,6 +601,25 @@ const normalizeCollectionModelSchema = (
         indexArg.key[0][0] === identityField &&
         indexArg.key[0][1] === 1,
     );
+    if (identityField === identityAsDocumentId) {
+      // The primary key is the only uniqueness authority for this field. A
+      // second unique index would have to be built on a live collection and
+      // could disagree with _id, so the declaration is refused rather than
+      // silently ignored.
+      if (hasIdentityIndex) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${identityField}" owns the document _id and must not declare its own unique index.`,
+        );
+      }
+      if (identityValueTypes[identityField] !== 'string') {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Identity field "${identityField}" must be a string identity to own the document _id.`,
+        );
+      }
+      continue;
+    }
     if (!hasIdentityIndex) {
       throw new SmartdataPersistenceError(
         'invalid_configuration',
@@ -577,6 +633,7 @@ const normalizeCollectionModelSchema = (
     persistedFields: Object.freeze([...persistedFields]),
     numericFields: Object.freeze([...numericFields]),
     identityFields: Object.freeze([...identityFields]),
+    ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
     identityValueTypes: Object.freeze({ ...identityValueTypes }),
     searchableFields: Object.freeze([...searchableFields]),
     indexes: Object.freeze([...indexesByName.values()]),
@@ -591,6 +648,7 @@ const normalizeCollectionModelSchema = (
       persistedFields: [...persistedFields].sort(compareSmartdataTopologyStrings),
       numericFields: [...numericFields].sort(compareSmartdataTopologyStrings),
       identityFields: [...identityFields].sort(compareSmartdataTopologyStrings),
+      ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
       identityValueTypes,
       searchableFields: [...searchableFields].sort(
         compareSmartdataTopologyStrings,
@@ -854,6 +912,7 @@ const definedModelSchemaSymbol = Symbol.for(
 const schemaFromDecoratorMetadata = (
   constructorArg: TCollectionModelConstructor<any>,
   collectionNameArg: string,
+  identityAsDocumentIdArg?: string,
 ): INormalizedCollectionModelSchema => {
   const ownMetadata = Object.prototype.hasOwnProperty.call(
     constructorArg,
@@ -885,6 +944,11 @@ const schemaFromDecoratorMetadata = (
     .map(([fieldArg]) => fieldArg);
   const indexes: ICollectionModelIndex[] = [];
   for (const uniqueField of metadata.uniqueIndexes || []) {
+    if (uniqueField === identityAsDocumentIdArg) {
+      // The document _id enforces this identity; a derived unique index would
+      // duplicate the primary key and require an index build on live data.
+      continue;
+    }
     indexes.push({
       name: `${uniqueField}_1`,
       key: { [uniqueField]: 1 },
@@ -924,6 +988,9 @@ const schemaFromDecoratorMetadata = (
       persistedFields,
       numericFields,
       identityFields: metadata.uniqueIndexes || [],
+      ...(identityAsDocumentIdArg !== undefined
+        ? { identityAsDocumentId: identityAsDocumentIdArg }
+        : {}),
       searchableFields: metadata.searchableFields || [],
       indexes,
     },
@@ -933,6 +1000,35 @@ const schemaFromDecoratorMetadata = (
   );
 };
 
+/**
+ * Exact persistence owns the stored `_id` as a MongoDB ObjectId, so a model
+ * cannot also hand the primary key to a declared identity field.
+ */
+const assertIdentityDocumentIdIsOrdinary = (
+  modelArg: TCollectionModelConstructor<any>,
+  identityAsDocumentIdArg: string,
+): void => {
+  if (hasExactPersistencePolicy(modelArg)) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Identity field "${identityAsDocumentIdArg}" cannot own the document _id for an exact-persistence model.`,
+    );
+  }
+};
+
+/**
+ * Returns the declared identity field a model stores as its document `_id`.
+ * Reading the bound schema resolver never resolves a database.
+ */
+export const getIdentityDocumentIdField = (modelArg: any): string | undefined => {
+  const resolver = modelArg?.[collectionModelSchemaResolverSymbol] as
+    | (() => INormalizedCollectionModelSchema)
+    | undefined;
+  return typeof resolver === 'function'
+    ? resolver().identityAsDocumentId
+    : undefined;
+};
+
 const installCollectionBinding = <
   TModel extends SmartDataDbDoc<any, any>,
 >(
@@ -1016,6 +1112,11 @@ export function defineCollectionModel<
       }
     | undefined;
   const inheritedSchema = inheritedConstructor?.[definedModelSchemaSymbol];
+  const identityAsDocumentId =
+    configArg.identityAsDocumentId ?? inheritedSchema?.identityAsDocumentId;
+  if (identityAsDocumentId !== undefined) {
+    assertIdentityDocumentIdIsOrdinary(modelArg, identityAsDocumentId);
+  }
   const normalizedSchema = normalizeCollectionModelSchema({
     ...configArg,
     persistedFields: [
@@ -1030,6 +1131,9 @@ export function defineCollectionModel<
       ...(inheritedSchema?.identityFields || []),
       ...(configArg.identityFields || []),
     ] as Array<keyof TModel & string>,
+    ...(identityAsDocumentId !== undefined
+      ? { identityAsDocumentId: identityAsDocumentId as TStringFieldKey<TModel> }
+      : {}),
     searchableFields: [
       ...(inheritedSchema?.searchableFields || []),
       ...(configArg.searchableFields || []),
@@ -1254,13 +1358,30 @@ export function Collection(
     const collectionName = normalizeCollectionName(
       optionsArg?.collectionName ?? constructor.name,
     );
+    const identityAsDocumentId = optionsArg?.identityAsDocumentId;
+    if (
+      identityAsDocumentId !== undefined
+      && (typeof identityAsDocumentId !== 'string' || identityAsDocumentId.length === 0)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Collection identityAsDocumentId must name a declared @unI() identity field.',
+      );
+    }
     return installCollectionBinding(
       constructor as TCollectionModelConstructor<any>,
       () => (dbArg instanceof SmartdataDb ? dbArg : dbArg()),
       () => {
+        if (identityAsDocumentId !== undefined) {
+          assertIdentityDocumentIdIsOrdinary(
+            constructor as TCollectionModelConstructor<any>,
+            identityAsDocumentId,
+          );
+        }
         return schemaFromDecoratorMetadata(
           constructor as TCollectionModelConstructor<any>,
           collectionName,
+          identityAsDocumentId,
         );
       },
     ) as any;
@@ -1719,6 +1840,11 @@ export class SmartdataCollection<T> {
    */
   public async markUniqueIndexes(keyArrayArg: string[] = []) {
     for (const key of keyArrayArg) {
+      if (key === this.modelSchema?.identityAsDocumentId) {
+        // The primary key already enforces this identity; building a second
+        // unique index on a live collection is exactly what the option avoids.
+        continue;
+      }
       if (!this.uniqueIndexes.includes(key)) {
         try {
           await this.mongoDbCollection.createIndex({ [key]: 1 }, {
@@ -1959,6 +2085,7 @@ export class SmartdataCollection<T> {
    * create an object in the database
    */
   private prepareOrdinaryInsert(documentArg: any): any {
+    documentArg = this.applyIdentityDocumentId(documentArg);
     const policy = this.modelSchema?.ordinaryPersistence;
     if (!policy) return documentArg;
     if (policy.idType === 'objectId' && !Object.prototype.hasOwnProperty.call(documentArg, '_id')) {
@@ -1967,11 +2094,46 @@ export class SmartdataCollection<T> {
     return validateOrdinaryStoredDocument(documentArg, policy, this.modelSchema!.persistedFields);
   }
 
+  /**
+   * Keys a stored document by its declared identity when the model opted into
+   * `identityAsDocumentId`. The identity keeps its own stored field, but reads
+   * address `_id`, so a document written before the option was declared is
+   * reachable only if its `_id` already equals that identity.
+   */
+  private applyIdentityDocumentId(documentArg: any): any {
+    const identityField = this.modelSchema?.identityAsDocumentId;
+    if (!identityField) return documentArg;
+    const identityValue = documentArg?.[identityField];
+    if (typeof identityValue !== 'string' || identityValue.trim().length === 0) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Identity field "${identityField}" must contain a non-empty string identity value to key the document.`,
+      );
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(documentArg, '_id')
+      && documentArg._id !== identityValue
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Identity field "${identityField}" owns the document _id and cannot be stored with a divergent _id.`,
+      );
+    }
+    return { ...documentArg, _id: identityValue };
+  }
+
+  /** True when stored documents need SmartData-owned preparation before a write. */
+  private get preparesStoredDocuments(): boolean {
+    return Boolean(
+      this.modelSchema?.ordinaryPersistence || this.modelSchema?.identityAsDocumentId,
+    );
+  }
+
   public async insert(
     dbDocArg: T & SmartDataDbDoc<T, unknown>,
     opts?: { session?: TSmartdataOrdinarySession }
   ): Promise<any> {
-    const preparedObject = this.modelSchema?.ordinaryPersistence
+    const preparedObject = this.preparesStoredDocuments
       ? this.prepareOrdinaryInsert(await dbDocArg.createSavableObject()) : undefined;
     return this.runWithOrdinarySession(
       opts?.session,
@@ -2049,7 +2211,7 @@ export class SmartdataCollection<T> {
         `insertMany requires a non-empty document batch for collection "${this.collectionName}".`,
       );
     }
-    const preparedObjects: any[] | undefined = this.modelSchema?.ordinaryPersistence ? [] : undefined;
+    const preparedObjects: any[] | undefined = this.preparesStoredDocuments ? [] : undefined;
     if (preparedObjects) {
       for (const dbDocArg of dbDocsArg) {
         preparedObjects.push(this.prepareOrdinaryInsert(await dbDocArg.createSavableObject()));
@@ -2118,14 +2280,23 @@ export class SmartdataCollection<T> {
       const first = documentsArg[0];
       await this.markUniqueIndexes(first.uniqueIndexes);
       await this.createRegularIndexes(first.regularIndexes || []);
+      // A document keyed by its identity is addressed through _id, and the
+      // seeded body must not repeat the immutable primary key: MongoDB derives
+      // it from the filter's equality condition on the insert branch.
+      const documentIdIdentity = this.modelSchema?.identityAsDocumentId === identityFieldArg;
       try {
-        const result = await this.mongoDbCollection.bulkWrite(prepared.map((document) => ({
-          updateOne: {
-            filter: { [identityFieldArg]: document[identityFieldArg] },
-            update: { $setOnInsert: document },
-            upsert: true,
-          },
-        })), { ordered: false, session: rawSessionArg, timeoutMS: optsArg.timeoutMS });
+        const result = await this.mongoDbCollection.bulkWrite(prepared.map((document) => {
+          const { _id: storedId, ...body } = document as Record<string, unknown>;
+          return {
+            updateOne: {
+              filter: documentIdIdentity
+                ? { _id: storedId as plugins.mongodb.Condition<plugins.mongodb.ObjectId> }
+                : { [identityFieldArg]: document[identityFieldArg] },
+              update: { $setOnInsert: documentIdIdentity ? body : document },
+              upsert: true,
+            },
+          };
+        }), { ordered: false, session: rawSessionArg, timeoutMS: optsArg.timeoutMS });
         if (result.upsertedCount + result.matchedCount !== prepared.length) {
           throw new SmartdataPersistenceError('unsupported_operation',
             'insertManyIfAbsent requires an acknowledged result for every identity.');