@lenne.tech/nest-server 12.1.1 → 12.3.0

package/src/core/common/persistence/data-store.interface.ts

@@ -54,6 +54,11 @@ export interface FindOptions {
    * Not combinable with `select`, as MongoDB does not combine them either.
    */
   exclude?: readonly string[];
+  /**
+   * Read tombstones too (a synchronized model's deleted records, `deletedAt` set). Every read of such a model leaves
+   * them out unless asked — only the sync module asks. No effect on other models.
+   */
+  includeTombstones?: boolean;
   /** Field names to return; the id is always returned */
   select?: readonly string[];
   skip?: number;
@@ -61,7 +66,15 @@ export interface FindOptions {
   sort?: Record<string, -1 | 1>;
 }
 
+/** Options of a read that has no paging (`count`, `distinct`, `findById`) */
+export interface ReadOptions {
+  /** See `FindOptions.includeTombstones` */
+  includeTombstones?: boolean;
+}
+
 export interface UpdateOptions {
+  /** Match tombstones too (a synchronized model's deleted records) — see `FindOptions.includeTombstones` */
+  includeTombstones?: boolean;
   /**
    * `false` leaves the update time (`updatedAt`) as it is — for bookkeeping writes such as a last-used stamp, which
    * must not read as a change of the record (Mongoose's `timestamps: false`). @default true
@@ -69,6 +82,17 @@ export interface UpdateOptions {
   timestamps?: boolean;
 }
 
+export interface DeleteOptions {
+  /**
+   * Remove the record for good. A synchronized model's delete otherwise leaves a tombstone (`deletedAt` set, the
+   * content cleared, the version incremented), which is how clients learn of it; a hard delete is the tombstone purge's
+   * (with `includeTombstones`). No effect on other models, whose delete always removes.
+   */
+  hardDelete?: boolean;
+  /** Match tombstones too — see `FindOptions.includeTombstones` */
+  includeTombstones?: boolean;
+}
+
 export interface PushOptions {
   /** Insert position (MongoDB `$position`) */
   position?: number;
@@ -99,28 +123,57 @@ export interface StoreCapabilities {
   textSearch: boolean;
   /** Multi-statement transactions */
   transactions: boolean;
-  /** Format of generated ids */
-  idType: 'objectId';
+  /** Format of the model's ids — `uuidv7` only for a synchronized model that declares it */
+  idType: 'objectId' | 'uuidv7';
+  /**
+   * How a synchronized model orders its changes (offline-sync plan §3.4): `seq` — the commit-ordered `syncSeq` (SQL);
+   * `clock` — the server clock `syncAt`, read with a window (MongoDB). Absent for a model that is not synchronized.
+   */
+  changeOrder?: 'clock' | 'seq';
+}
+
+/** The database's clock as a pull over `changeOrder: 'clock'` reads it (offline-sync plan §3.4) */
+export interface ChangeClock {
+  /** The database server's current time */
+  now: Date;
+  /**
+   * The window W: how long a write may take from its stamp until it is visible. A pull run starts this far below the
+   * previous run's start, so a change stamped before that start but committed after it is not passed.
+   */
+  windowMs: number;
 }
 
 export interface DataStore<T = Record<string, any>> {
   readonly capabilities: StoreCapabilities;
+  /**
+   * The database's clock and the window W of a synchronized model whose change order is the clock
+   * (`capabilities.changeOrder === 'clock'`); absent on every other store. What the sync module reads instead of
+   * asking for the driver.
+   */
+  changeClock?(): Promise<ChangeClock>;
   /** The database behind the store (`mongodb`, `postgres`, …) */
   readonly driver: string;
   readonly modelName: string;
 
-  count(where?: Where<T>): Promise<number>;
-  deleteById(id: string): Promise<null | StoredRecord<T>>;
-  /** Remove every record matching `where`; returns how many were removed. */
-  deleteMany(where: Where<T>): Promise<number>;
+  count(where?: Where<T>, options?: ReadOptions): Promise<number>;
+  /**
+   * Remove the record and return it as it was; `null` when there is none. On a synchronized model: turn it into a
+   * tombstone instead, unless `hardDelete` (see `DeleteOptions`).
+   */
+  deleteById(id: string, options?: DeleteOptions): Promise<null | StoredRecord<T>>;
+  /** Remove every record matching `where`; returns how many were removed (tombstoned on a synchronized model). */
+  deleteMany(where: Where<T>, options?: DeleteOptions): Promise<number>;
   /**
    * Remove the first record matching `where`, atomically (MongoDB's `findOneAndDelete`), and return it; `null` when
-   * nothing matches.
+   * nothing matches (tombstoned on a synchronized model).
    */
-  deleteOne(where: Where<T>): Promise<null | StoredRecord<T>>;
-  distinct(field: string, where?: Where<T>): Promise<unknown[]>;
+  deleteOne(where: Where<T>, options?: DeleteOptions): Promise<null | StoredRecord<T>>;
+  distinct(field: string, where?: Where<T>, options?: ReadOptions): Promise<unknown[]>;
   find(where?: Where<T>, options?: FindOptions): Promise<StoredRecord<T>[]>;
-  findById(id: string, options?: Pick<FindOptions, 'exclude' | 'select'>): Promise<null | StoredRecord<T>>;
+  findById(
+    id: string,
+    options?: Pick<FindOptions, 'exclude' | 'includeTombstones' | 'select'>,
+  ): Promise<null | StoredRecord<T>>;
   findOne(where: Where<T>, options?: Omit<FindOptions, 'limit' | 'skip'>): Promise<null | StoredRecord<T>>;
   insert(record: Partial<T>): Promise<StoredRecord<T>>;
   /**
@@ -145,11 +198,11 @@ export interface DataStore<T = Record<string, any>> {
   /** Apply `update` to the record and return it as stored afterwards; `null` when there is none. */
   updateById(id: string, update: DataStoreUpdate<T>, options?: UpdateOptions): Promise<null | StoredRecord<T>>;
   /** Apply `update` to every record matching `where`; returns how many records matched. */
-  updateMany(where: Where<T>, update: DataStoreUpdate<T>): Promise<number>;
+  updateMany(where: Where<T>, update: DataStoreUpdate<T>, options?: UpdateOptions): Promise<number>;
   /**
    * Apply `update` to the first record matching `where`, atomically: the record still matches when it is changed, and
    * concurrent callers never change the same record on the strength of one match (MongoDB's `findOneAndUpdate`).
    * Returns the record as stored afterwards; `null` when nothing matches.
    */
-  updateOne(where: Where<T>, update: DataStoreUpdate<T>): Promise<null | StoredRecord<T>>;
+  updateOne(where: Where<T>, update: DataStoreUpdate<T>, options?: UpdateOptions): Promise<null | StoredRecord<T>>;
 }

package/src/core/common/persistence/id-format.ts

@@ -41,3 +41,29 @@ export function generateId(): string {
   bytes.writeUIntBE(counter, 9, 3);
   return bytes.toString('hex');
 }
+
+/**
+ * A uuidv7 as the framework stores it (plan §3.5): lowercase, hyphenated, version nibble `7`, variant `8`–`b`. The id
+ * format a synchronized model may choose instead of the ObjectId (`@PersistedModel({ sync: { idFormat: 'uuidv7' } })`).
+ */
+const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/** Whether a value is a uuidv7 in the stored form — lowercase only, so one id has exactly one spelling */
+export function isUuidV7(value: unknown): value is string {
+  return typeof value === 'string' && UUID_V7.test(value);
+}
+
+/**
+ * A new uuidv7 (RFC 9562): 48 bits of milliseconds, then 74 random bits — sortable by creation time like an ObjectId,
+ * but with nothing after the timestamp that one observed id would let anybody predict.
+ */
+export function generateUuidV7(): string {
+  const bytes = randomBytes(16);
+  const millis = Date.now();
+  bytes.writeUIntBE(Math.floor(millis / 0x10000), 0, 4);
+  bytes.writeUInt16BE(millis % 0x10000, 4);
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/core/common/persistence/model-descriptor.interface.ts

@@ -77,12 +77,24 @@ export interface IndexDescriptor {
   options: Record<string, unknown>;
 }
 
+/** The id format of a synchronized model: one per model, never mixed (offline-sync plan §3.5) */
+export type SyncIdFormat = 'objectId' | 'uuidv7';
+
+/** How a model is synchronized to offline clients — see `sync-model.ts` */
+export interface SyncDescriptor {
+  idFormat: SyncIdFormat;
+  /** User-id fields a tombstone keeps besides `tenantId` */
+  scope: readonly string[];
+}
+
 export interface ModelDescriptor {
   /** Explicit collection / table name, when the model declares one */
   collection?: string;
   fields: Record<string, FieldDescriptor>;
   indexes: IndexDescriptor[];
   name: string;
+  /** Present when the model is synchronized (`@PersistedModel({ sync })`); absent for every other model */
+  sync?: SyncDescriptor;
   /** Whether the model carries a `tenantId` — the same criterion the tenant plugin uses */
   tenantScoped: boolean;
   /** `createdAt` / `updatedAt` maintenance: `true`, `false`, or the configured field names */

package/src/core/common/persistence/model-metadata.registry.ts

@@ -2,6 +2,7 @@ import type { FieldDescriptor, FieldKind, IndexDescriptor, ModelDescriptor } fro
 import { declaredSchemaView } from './mongo/declared-schema.view.js';
 import { type DeclaredSchema, isDeclaredSchema } from './mongo/model-declarations.js';
 import { SchemaFactory } from './mongo/mongoose-compat.js';
+import { type SyncDescriptor, withSyncDescriptor } from './sync-model.js';
 
 /**
  * Registry of database-neutral model descriptors.
@@ -70,12 +71,40 @@ export function describeModelClass(modelClass: abstract new (...args: any[]) =>
   return descriptor;
 }
 
+/**
+ * The descriptor of a schema as it was declared, per schema object and model name. A synchronized model's Mongoose
+ * schema gains its system paths and partial indexes once it is registered (`mongo/sync-schema.plugin.ts`); a second
+ * registration of the same schema must describe what was declared, not what the plugin added.
+ */
+const declaredDescriptors = new WeakMap<object, Map<string, ModelDescriptor>>();
+
 /**
  * Register the schema a model is persisted with, under its model name. A later registration under
  * the same name replaces the earlier one — the last `forFeature` wins, as it does in Mongoose.
+ *
+ * `sync` makes it the descriptor of a synchronized model (`sync-model.ts`).
  */
-export function registerModelSchema(name: string, schema: DeclaredSchema | SchemaLike): ModelDescriptor {
-  const descriptor = describeSchema(name, schema);
+export function registerModelSchema(
+  name: string,
+  schema: DeclaredSchema | SchemaLike,
+  sync?: SyncDescriptor,
+): ModelDescriptor {
+  let descriptor: ModelDescriptor;
+  if (sync) {
+    let byName = declaredDescriptors.get(schema);
+    if (!byName) {
+      byName = new Map();
+      declaredDescriptors.set(schema, byName);
+    }
+    let declared = byName.get(name);
+    if (!declared) {
+      declared = describeSchema(name, schema);
+      byName.set(name, declared);
+    }
+    descriptor = withSyncDescriptor(declared, sync);
+  } else {
+    descriptor = describeSchema(name, schema);
+  }
   descriptorsByName.set(name, descriptor);
   return descriptor;
 }