@lpdjs/firestore-repo-service 2.2.6 → 2.2.8

package/dist/{types-Z9Qy8Xmx.d.ts → types-BESS89Fu.d.cts}

@@ -1,6 +1,7 @@
 import * as zod from 'zod';
 import { z } from 'zod';
 import { HttpsOptions } from 'firebase-functions/v2/https';
+import { H as HistoryConfigForModel, a as HistoryMethods } from './read-DfXXxhO4.cjs';
 import { DocumentReference, Firestore, DocumentSnapshot, WhereFilterOp, Query, CollectionReference, WriteBatch, Transaction } from 'firebase-admin/firestore';
 
 /**
@@ -145,7 +146,7 @@ interface RelationConfig<TRepoKey extends string = string, TForeignKey extends s
  */
 type RelationalKeys<T = any, TMapping = any> = {
     [K in keyof T]?: TMapping extends Record<string, any> ? {
-        [R in keyof TMapping]: TMapping[R] extends RepositoryConfig<any, infer FKeys, any, any, any, any, any, any> ? {
+        [R in keyof TMapping]: TMapping[R] extends RepositoryConfig<any, infer FKeys, any, any, any, any, any, any, any, any, any> ? {
             repo: R;
             key: FKeys[number];
             type: "one" | "many";
@@ -165,7 +166,7 @@ type RelationalKeys<T = any, TMapping = any> = {
  * @template TCreatedKey - The field name to store the creation timestamp (optional)
  * @template TUpdatedKey - The field name to store the update timestamp (optional)
  */
-interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryKeys extends readonly (keyof T)[], TIsGroup extends boolean = boolean, TRefCb = any, TRelationalKeys = {}, TDocumentKey extends keyof T = keyof T, TPathKey extends keyof T | undefined = undefined, TCreatedKey extends keyof T | undefined = undefined, TUpdatedKey extends keyof T | undefined = undefined> {
+interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryKeys extends readonly (keyof T)[], TIsGroup extends boolean = boolean, TRefCb = any, TRelationalKeys = {}, TDocumentKey extends keyof T = keyof T, TPathKey extends keyof T | undefined = undefined, TCreatedKey extends keyof T | undefined = undefined, TUpdatedKey extends keyof T | undefined = undefined, THistoryEnabled extends boolean = false> {
     path: string;
     isGroup: TIsGroup;
     foreignKeys: TForeignKeys;
@@ -179,6 +180,16 @@ interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryK
     schema?: zod.ZodObject<any>;
     refCb?: TRefCb;
     relationalKeys?: TRelationalKeys;
+    /**
+     * Optional change-history configuration. When `enabled: true`, the
+     * `repo.history.*` read API is exposed and `createHistoryTriggers(...)`
+     * will register Firestore triggers for this repo.
+     *
+     * @see import("../history/types").HistoryConfigForModel
+     */
+    history?: HistoryConfigForModel<T> & {
+        enabled: THistoryEnabled;
+    };
     documentRef: TRefCb extends undefined ? TIsGroup extends true ? (...pathSegments: string[]) => DocumentReference : (docId: string) => DocumentReference : ExtractDocumentRefSignature<TRefCb>;
     update: TRefCb extends undefined ? TIsGroup extends true ? (...args: [...string[], Partial<T>]) => Promise<T> : (docId: string, data: Partial<T>) => Promise<T> : ExtractUpdateSignature<TRefCb, T>;
 }
@@ -380,17 +391,17 @@ interface PaginationWithIncludeOptionsTyped<T, TRelationalKeys, K extends keyof
  * Helper type to get the system keys (documentKey + pathKey + updatedKey) that should be excluded from updates
  * @internal
  */
-type SystemKeys<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>;
+type SystemKeys<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>;
 /**
  * Type for updatable data - excludes documentKey, pathKey and updatedKey (all auto-managed)
  * @internal
  */
-type UpdatableData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = Omit<Partial<T["type"]>, SystemKeys<T>>;
+type UpdatableData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = Omit<Partial<T["type"]>, SystemKeys<T>>;
 /**
  * Type for create data - excludes pathKey, createdKey and updatedKey (auto-managed), documentKey is optional
  * @internal
  */
-type CreateData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = Omit<T["type"], T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["createdKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>> & {
+type CreateData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = Omit<T["type"], T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["createdKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>> & {
     [K in T["documentKey"]]?: T["type"][K];
 };
 /**
@@ -413,7 +424,7 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
  * Return type is narrowed based on whether returnDoc is true.
  * @internal
  */
-type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = {
+type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = {
     [K in TConfig["foreignKeys"][number] as K extends string ? `by${Capitalize<K>}` : never]: <ReturnDoc extends boolean = false>(value: TConfig["type"][K extends keyof TConfig["type"] ? K : never], options?: ReturnDoc | (GetOptions<TConfig["type"]> & {
         returnDoc?: ReturnDoc;
     })) => Promise<GetResult<TConfig["type"], ReturnDoc>>;
@@ -422,13 +433,13 @@ type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any
  * Generates query.by* methods from query keys
  * @internal
  */
-type GenerateQueryMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = {
+type GenerateQueryMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = {
     [K in TConfig["queryKeys"][number] as K extends string ? `by${Capitalize<K>}` : never]: (value: TConfig["type"][K], options?: QueryOptions<TConfig["type"]>) => Promise<TConfig["type"][]>;
 };
 /**
  * Configured repository with organized methods
  */
-type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = {
+type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = {
     /** @internal Phantom property to expose the model type for generic extraction */
     readonly _modelType: T["type"];
     /** @internal Whether this is a collectionGroup repository */
@@ -512,6 +523,13 @@ type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, an
     populate: <K extends keyof NonNullable<T["relationalKeys"]>, TDoc extends Pick<T["type"], K & keyof T["type"]>>(document: TDoc, relationKeyOrOptions: K | K[] | PopulateOptionsTyped<NonNullable<T["relationalKeys"]>, K>) => Promise<TDoc & {
         populated: UnionToIntersection<K extends keyof NonNullable<T["relationalKeys"]> ? ExtractPopulatedFromRelation<NonNullable<T["relationalKeys"]>[K], K & string> : Record<string, never>>;
     }>;
+    /**
+     * Change-history namespace. Present at the type level when the repo is
+     * configured with `history.enabled: true`, otherwise `undefined` at runtime.
+     * Kept optional (rather than conditional) so `ConfiguredRepository<any>`
+     * stays assignable from any concrete repo config.
+     */
+    history?: HistoryMethods<T["type"]>;
 };
 
 /**
@@ -545,13 +563,13 @@ interface OpenAPISpecOptions {
  * `createRepositoryConfig(schema)`).
  * @internal
  */
-type RepoModelType<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<infer T, any, any, any, any, any, any, any, any, any> ? T : never : never;
+type RepoModelType<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<infer T, any, any, any, any, any, any, any, any, any, any> ? T : never : never;
 /**
  * Extracts the auto-managed system keys (documentKey, pathKey, createdKey, updatedKey)
  * from a `ConfiguredRepository`. These keys must never appear in create/update payloads.
  * @internal
  */
-type RepoSystemKeys<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<any, any, any, any, any, any, infer TDocKey, infer TPathKey, infer TCreatedKey, infer TUpdatedKey> ? (TDocKey extends string ? TDocKey : never) | (TPathKey extends string ? TPathKey : never) | (TCreatedKey extends string ? TCreatedKey : never) | (TUpdatedKey extends string ? TUpdatedKey : never) : never : never;
+type RepoSystemKeys<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<any, any, any, any, any, any, infer TDocKey, infer TPathKey, infer TCreatedKey, infer TUpdatedKey, any> ? (TDocKey extends string ? TDocKey : never) | (TPathKey extends string ? TPathKey : never) | (TCreatedKey extends string ? TCreatedKey : never) | (TUpdatedKey extends string ? TUpdatedKey : never) : never : never;
 /**
  * `true` when `T` is `any`  (the `0 extends (1 & T)` trick).
  * @internal
@@ -583,7 +601,7 @@ type RepoFieldPath<TRepo> = IsAny<TRepo> extends true ? string : IsAny<RepoModel
  * Falls back to `string` when `TRepo` is unresolved (`any`).
  * @internal
  */
-type RepoRelationKeys<TRepo> = IsAny<TRepo> extends true ? string : TRepo extends ConfiguredRepository<RepositoryConfig<any, any, any, any, any, infer TRelKeys, any, any, any, any>> ? IsAny<TRelKeys> extends true ? string : keyof TRelKeys & string : string;
+type RepoRelationKeys<TRepo> = IsAny<TRepo> extends true ? string : TRepo extends ConfiguredRepository<RepositoryConfig<any, any, any, any, any, infer TRelKeys, any, any, any, any, any>> ? IsAny<TRelKeys> extends true ? string : keyof TRelKeys & string : string;
 /**
  * Configuration for a single repository in the CRUD server.
  *
@@ -650,7 +668,7 @@ interface CrudRepoConfig<TRepo extends ConfiguredRepository<any> = ConfiguredRep
 interface CrudRepoEntry {
     name: string;
     path: string;
-    repo: ConfiguredRepository<RepositoryConfig<any, any, any, any, any, any, any, any, any, any>>;
+    repo: ConfiguredRepository<RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>>;
     schema: z.ZodObject<any>;
     /** Keys automatically managed by Firestore (docId, path, timestamps) — excluded from create/update payloads */
     systemKeys: string[];

package/dist/{types-Z9Qy8Xmx.d.cts → types-BVUFVcpl.d.ts}

@@ -1,6 +1,7 @@
 import * as zod from 'zod';
 import { z } from 'zod';
 import { HttpsOptions } from 'firebase-functions/v2/https';
+import { H as HistoryConfigForModel, a as HistoryMethods } from './read-DfXXxhO4.js';
 import { DocumentReference, Firestore, DocumentSnapshot, WhereFilterOp, Query, CollectionReference, WriteBatch, Transaction } from 'firebase-admin/firestore';
 
 /**
@@ -145,7 +146,7 @@ interface RelationConfig<TRepoKey extends string = string, TForeignKey extends s
  */
 type RelationalKeys<T = any, TMapping = any> = {
     [K in keyof T]?: TMapping extends Record<string, any> ? {
-        [R in keyof TMapping]: TMapping[R] extends RepositoryConfig<any, infer FKeys, any, any, any, any, any, any> ? {
+        [R in keyof TMapping]: TMapping[R] extends RepositoryConfig<any, infer FKeys, any, any, any, any, any, any, any, any, any> ? {
             repo: R;
             key: FKeys[number];
             type: "one" | "many";
@@ -165,7 +166,7 @@ type RelationalKeys<T = any, TMapping = any> = {
  * @template TCreatedKey - The field name to store the creation timestamp (optional)
  * @template TUpdatedKey - The field name to store the update timestamp (optional)
  */
-interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryKeys extends readonly (keyof T)[], TIsGroup extends boolean = boolean, TRefCb = any, TRelationalKeys = {}, TDocumentKey extends keyof T = keyof T, TPathKey extends keyof T | undefined = undefined, TCreatedKey extends keyof T | undefined = undefined, TUpdatedKey extends keyof T | undefined = undefined> {
+interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryKeys extends readonly (keyof T)[], TIsGroup extends boolean = boolean, TRefCb = any, TRelationalKeys = {}, TDocumentKey extends keyof T = keyof T, TPathKey extends keyof T | undefined = undefined, TCreatedKey extends keyof T | undefined = undefined, TUpdatedKey extends keyof T | undefined = undefined, THistoryEnabled extends boolean = false> {
     path: string;
     isGroup: TIsGroup;
     foreignKeys: TForeignKeys;
@@ -179,6 +180,16 @@ interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryK
     schema?: zod.ZodObject<any>;
     refCb?: TRefCb;
     relationalKeys?: TRelationalKeys;
+    /**
+     * Optional change-history configuration. When `enabled: true`, the
+     * `repo.history.*` read API is exposed and `createHistoryTriggers(...)`
+     * will register Firestore triggers for this repo.
+     *
+     * @see import("../history/types").HistoryConfigForModel
+     */
+    history?: HistoryConfigForModel<T> & {
+        enabled: THistoryEnabled;
+    };
     documentRef: TRefCb extends undefined ? TIsGroup extends true ? (...pathSegments: string[]) => DocumentReference : (docId: string) => DocumentReference : ExtractDocumentRefSignature<TRefCb>;
     update: TRefCb extends undefined ? TIsGroup extends true ? (...args: [...string[], Partial<T>]) => Promise<T> : (docId: string, data: Partial<T>) => Promise<T> : ExtractUpdateSignature<TRefCb, T>;
 }
@@ -380,17 +391,17 @@ interface PaginationWithIncludeOptionsTyped<T, TRelationalKeys, K extends keyof
  * Helper type to get the system keys (documentKey + pathKey + updatedKey) that should be excluded from updates
  * @internal
  */
-type SystemKeys<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>;
+type SystemKeys<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>;
 /**
  * Type for updatable data - excludes documentKey, pathKey and updatedKey (all auto-managed)
  * @internal
  */
-type UpdatableData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = Omit<Partial<T["type"]>, SystemKeys<T>>;
+type UpdatableData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = Omit<Partial<T["type"]>, SystemKeys<T>>;
 /**
  * Type for create data - excludes pathKey, createdKey and updatedKey (auto-managed), documentKey is optional
  * @internal
  */
-type CreateData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = Omit<T["type"], T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["createdKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>> & {
+type CreateData<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = Omit<T["type"], T["documentKey"] | Extract<T["pathKey"], keyof T["type"]> | Extract<T["createdKey"], keyof T["type"]> | Extract<T["updatedKey"], keyof T["type"]>> & {
     [K in T["documentKey"]]?: T["type"][K];
 };
 /**
@@ -413,7 +424,7 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
  * Return type is narrowed based on whether returnDoc is true.
  * @internal
  */
-type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = {
+type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = {
     [K in TConfig["foreignKeys"][number] as K extends string ? `by${Capitalize<K>}` : never]: <ReturnDoc extends boolean = false>(value: TConfig["type"][K extends keyof TConfig["type"] ? K : never], options?: ReturnDoc | (GetOptions<TConfig["type"]> & {
         returnDoc?: ReturnDoc;
     })) => Promise<GetResult<TConfig["type"], ReturnDoc>>;
@@ -422,13 +433,13 @@ type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any
  * Generates query.by* methods from query keys
  * @internal
  */
-type GenerateQueryMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = {
+type GenerateQueryMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = {
     [K in TConfig["queryKeys"][number] as K extends string ? `by${Capitalize<K>}` : never]: (value: TConfig["type"][K], options?: QueryOptions<TConfig["type"]>) => Promise<TConfig["type"][]>;
 };
 /**
  * Configured repository with organized methods
  */
-type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any>> = {
+type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>> = {
     /** @internal Phantom property to expose the model type for generic extraction */
     readonly _modelType: T["type"];
     /** @internal Whether this is a collectionGroup repository */
@@ -512,6 +523,13 @@ type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, an
     populate: <K extends keyof NonNullable<T["relationalKeys"]>, TDoc extends Pick<T["type"], K & keyof T["type"]>>(document: TDoc, relationKeyOrOptions: K | K[] | PopulateOptionsTyped<NonNullable<T["relationalKeys"]>, K>) => Promise<TDoc & {
         populated: UnionToIntersection<K extends keyof NonNullable<T["relationalKeys"]> ? ExtractPopulatedFromRelation<NonNullable<T["relationalKeys"]>[K], K & string> : Record<string, never>>;
     }>;
+    /**
+     * Change-history namespace. Present at the type level when the repo is
+     * configured with `history.enabled: true`, otherwise `undefined` at runtime.
+     * Kept optional (rather than conditional) so `ConfiguredRepository<any>`
+     * stays assignable from any concrete repo config.
+     */
+    history?: HistoryMethods<T["type"]>;
 };
 
 /**
@@ -545,13 +563,13 @@ interface OpenAPISpecOptions {
  * `createRepositoryConfig(schema)`).
  * @internal
  */
-type RepoModelType<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<infer T, any, any, any, any, any, any, any, any, any> ? T : never : never;
+type RepoModelType<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<infer T, any, any, any, any, any, any, any, any, any, any> ? T : never : never;
 /**
  * Extracts the auto-managed system keys (documentKey, pathKey, createdKey, updatedKey)
  * from a `ConfiguredRepository`. These keys must never appear in create/update payloads.
  * @internal
  */
-type RepoSystemKeys<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<any, any, any, any, any, any, infer TDocKey, infer TPathKey, infer TCreatedKey, infer TUpdatedKey> ? (TDocKey extends string ? TDocKey : never) | (TPathKey extends string ? TPathKey : never) | (TCreatedKey extends string ? TCreatedKey : never) | (TUpdatedKey extends string ? TUpdatedKey : never) : never : never;
+type RepoSystemKeys<TRepo> = TRepo extends ConfiguredRepository<infer C> ? C extends RepositoryConfig<any, any, any, any, any, any, infer TDocKey, infer TPathKey, infer TCreatedKey, infer TUpdatedKey, any> ? (TDocKey extends string ? TDocKey : never) | (TPathKey extends string ? TPathKey : never) | (TCreatedKey extends string ? TCreatedKey : never) | (TUpdatedKey extends string ? TUpdatedKey : never) : never : never;
 /**
  * `true` when `T` is `any`  (the `0 extends (1 & T)` trick).
  * @internal
@@ -583,7 +601,7 @@ type RepoFieldPath<TRepo> = IsAny<TRepo> extends true ? string : IsAny<RepoModel
  * Falls back to `string` when `TRepo` is unresolved (`any`).
  * @internal
  */
-type RepoRelationKeys<TRepo> = IsAny<TRepo> extends true ? string : TRepo extends ConfiguredRepository<RepositoryConfig<any, any, any, any, any, infer TRelKeys, any, any, any, any>> ? IsAny<TRelKeys> extends true ? string : keyof TRelKeys & string : string;
+type RepoRelationKeys<TRepo> = IsAny<TRepo> extends true ? string : TRepo extends ConfiguredRepository<RepositoryConfig<any, any, any, any, any, infer TRelKeys, any, any, any, any, any>> ? IsAny<TRelKeys> extends true ? string : keyof TRelKeys & string : string;
 /**
  * Configuration for a single repository in the CRUD server.
  *
@@ -650,7 +668,7 @@ interface CrudRepoConfig<TRepo extends ConfiguredRepository<any> = ConfiguredRep
 interface CrudRepoEntry {
     name: string;
     path: string;
-    repo: ConfiguredRepository<RepositoryConfig<any, any, any, any, any, any, any, any, any, any>>;
+    repo: ConfiguredRepository<RepositoryConfig<any, any, any, any, any, any, any, any, any, any, any>>;
     schema: z.ZodObject<any>;
     /** Keys automatically managed by Firestore (docId, path, timestamps) — excluded from create/update payloads */
     systemKeys: string[];

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@lpdjs/firestore-repo-service",
-  "version": "2.2.6",
+  "version": "2.2.8",
+  "workspaces": [
+    "test/functions"
+  ],
   "description": "⚡ Type-safe Firestore ORM with auto-generated repositories, advanced queries, relations with typed select, pagination with include, batch/bulk operations, aggregations and transactions.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -37,6 +40,16 @@
         "default": "./dist/sync/bigquery.js"
       }
     },
+    "./history": {
+      "require": {
+        "types": "./dist/history/index.d.cts",
+        "default": "./dist/history/index.cjs"
+      },
+      "import": {
+        "types": "./dist/history/index.d.ts",
+        "default": "./dist/history/index.js"
+      }
+    },
     "./servers": {
       "require": {
         "types": "./dist/servers/index.d.cts",
@@ -84,6 +97,9 @@
       ],
       "sync/bigquery": [
         "./dist/sync/bigquery.d.ts"
+      ],
+      "history": [
+        "./dist/history/index.d.ts"
       ]
     }
   },