@lpdjs/firestore-repo-service 2.1.2 → 2.1.4

package/dist/{types-PzZ0APQ_.d.cts → types-DE9lapG8.d.cts}

@@ -5,6 +5,8 @@
  * worker) and any SQL backend (BigQuery, PostgreSQL, …). Only the adapter
  * touches the database SDK; everything else works with these abstractions.
  */
+/** A value that can be provided directly or as a lazy factory function. */
+type OrFactory<T> = T | (() => T);
 /** A single column in a SQL table. */
 interface SqlColumn {
     /** Column name (snake_case recommended for SQL) */
@@ -36,10 +38,6 @@ interface SqlDialect {
     mapType(logical: LogicalType): string;
     /** Wrap an identifier (table / column name) for the dialect */
     quoteIdentifier(id: string): string;
-    /** Generate a full CREATE TABLE statement */
-    createTableDDL(table: SqlTableDef): string;
-    /** Generate ALTER TABLE ADD COLUMN statement(s) for new columns */
-    addColumnsDDL(tableName: string, columns: SqlColumn[]): string;
 }
 /**
  * Logical types used as an intermediate representation between Zod types
@@ -94,6 +92,16 @@ interface SqlAdapter {
      * Delete rows by primary-key values.
      */
     deleteRows(tableName: string, primaryKey: string, ids: string[]): Promise<void>;
+    /**
+     * Add columns to an existing table.
+     * The adapter is responsible for qualifying table names (e.g. dataset.table).
+     */
+    addColumns(tableName: string, columns: SqlColumn[]): Promise<void>;
+    /**
+     * Execute a raw SQL statement.
+     * The adapter is responsible for qualifying any table references.
+     */
+    executeRaw(sql: string): Promise<void>;
 }
 /** Per-repository sync options, typed to the repo's field names. */
 interface RepoSyncConfig<F extends string = string> {
@@ -202,7 +210,7 @@ interface GenerateDDLConfig<M = Record<string, any>> {
 /**
  * HTTP Basic Auth configuration for the sync admin.
  */
-interface SyncAdminBasicAuth {
+interface adminsyncBasicAuth {
     type: "basic";
     /** Realm displayed in the browser login dialog */
     realm?: string;
@@ -212,7 +220,7 @@ interface SyncAdminBasicAuth {
 /**
  * Feature flags controlling which sync admin endpoints are enabled.
  */
-interface SyncAdminFeaturesFlag {
+interface adminsyncFeaturesFlag {
     /** Show pending queue state (default: false) */
     viewQueue?: boolean;
     /** Allow force-syncing an entire collection (default: false) */
@@ -227,13 +235,13 @@ interface SyncAdminFeaturesFlag {
  * When provided in `FirestoreSyncConfig.admin`, an `onRequest` Cloud Function
  * handler is created and added to `sync.functions`.
  */
-interface SyncAdminConfig {
+interface adminsyncConfig {
     /** Authentication guard — HTTP Basic Auth or custom middleware function */
-    auth?: SyncAdminBasicAuth | ((req: any, res: any, next: () => void) => void | Promise<void>);
+    auth?: adminsyncBasicAuth | ((req: any, res: any, next: () => void) => void | Promise<void>);
     /** Base URL path (default: "/sync-admin") */
     basePath?: string;
     /** Feature flags controlling which endpoints are enabled */
-    featuresFlag?: SyncAdminFeaturesFlag;
+    featuresFlag?: adminsyncFeaturesFlag;
     /**
      * `onRequest` from `firebase-functions/https` (or `firebase-functions/v2/https`).
      * When provided, the admin handler is automatically wrapped as a Cloud Function.
@@ -248,10 +256,21 @@ interface SyncAdminConfig {
 }
 /** Options for `createFirestoreSync()` — the unified wrapper. */
 interface FirestoreSyncConfig<M = Record<string, any>> {
-    /** External dependencies — all Firebase/PubSub modules */
-    deps: SyncDeps;
-    /** SQL adapter to flush data to */
-    adapter: SqlAdapter;
+    /**
+     * External dependencies — all Firebase/PubSub modules.
+     * `pubsub` can be a factory `() => PubSub` for lazy initialization
+     * (avoids creating gRPC channels at module-load time for functions that
+     * don't need PubSub, e.g. the admin or CRUD servers).
+     */
+    deps: Omit<SyncDeps, "pubsub"> & {
+        pubsub: OrFactory<PubSubClientDep>;
+    };
+    /**
+     * SQL adapter to flush data to.
+     * Can be a factory `() => adapter` for lazy initialization
+     * (avoids connecting to BigQuery / SQL at module-load time).
+     */
+    adapter: OrFactory<SqlAdapter>;
     /** PubSub topic name prefix (topics will be `{prefix}-{repoName}`) */
     topicPrefix?: string;
     /** Max rows per flush batch (default: 100) */
@@ -261,13 +280,13 @@ interface FirestoreSyncConfig<M = Record<string, any>> {
     /** Auto-create/migrate tables on first event (default: false) */
     autoMigrate?: boolean;
     /**
-     * Optional sync admin endpoint. When provided, a `syncAdmin` handler is
+     * Optional sync admin endpoint. When provided, a `adminsync` handler is
      * added to `sync.functions` exposing health-check, force-sync, and queue
      * inspection endpoints behind authentication.
      */
-    admin?: SyncAdminConfig;
+    admin?: adminsyncConfig;
     /** Per-repo overrides (shared between triggers and worker) */
     repos?: TypedRepoSyncConfigs<M>;
 }
 
-export type { FirestoreSyncConfig as F, GenerateDDLConfig as G, LogicalType as L, PubSubClientDep as P, RepoSyncConfig as R, SqlDialect as S, SqlColumn as a, SqlTableDef as b, SqlAdapter as c, SyncEvent as d, SyncWorkerConfig as e, SyncTriggersConfig as f, SyncAdminConfig as g, SyncOperation as h, SyncDeps as i, FirestoreTriggersDep as j, PubSubHandlerDep as k, SyncAdminBasicAuth as l, SyncAdminFeaturesFlag as m };
+export type { FirestoreSyncConfig as F, GenerateDDLConfig as G, LogicalType as L, OrFactory as O, PubSubClientDep as P, RepoSyncConfig as R, SqlAdapter as S, SyncEvent as a, adminsyncConfig as b, SqlDialect as c, SqlColumn as d, SqlTableDef as e, SyncTriggersConfig as f, SyncWorkerConfig as g, FirestoreTriggersDep as h, PubSubHandlerDep as i, SyncDeps as j, SyncOperation as k, adminsyncBasicAuth as l, adminsyncFeaturesFlag as m };

package/dist/{types-PzZ0APQ_.d.ts → types-DE9lapG8.d.ts}

@@ -5,6 +5,8 @@
  * worker) and any SQL backend (BigQuery, PostgreSQL, …). Only the adapter
  * touches the database SDK; everything else works with these abstractions.
  */
+/** A value that can be provided directly or as a lazy factory function. */
+type OrFactory<T> = T | (() => T);
 /** A single column in a SQL table. */
 interface SqlColumn {
     /** Column name (snake_case recommended for SQL) */
@@ -36,10 +38,6 @@ interface SqlDialect {
     mapType(logical: LogicalType): string;
     /** Wrap an identifier (table / column name) for the dialect */
     quoteIdentifier(id: string): string;
-    /** Generate a full CREATE TABLE statement */
-    createTableDDL(table: SqlTableDef): string;
-    /** Generate ALTER TABLE ADD COLUMN statement(s) for new columns */
-    addColumnsDDL(tableName: string, columns: SqlColumn[]): string;
 }
 /**
  * Logical types used as an intermediate representation between Zod types
@@ -94,6 +92,16 @@ interface SqlAdapter {
      * Delete rows by primary-key values.
      */
     deleteRows(tableName: string, primaryKey: string, ids: string[]): Promise<void>;
+    /**
+     * Add columns to an existing table.
+     * The adapter is responsible for qualifying table names (e.g. dataset.table).
+     */
+    addColumns(tableName: string, columns: SqlColumn[]): Promise<void>;
+    /**
+     * Execute a raw SQL statement.
+     * The adapter is responsible for qualifying any table references.
+     */
+    executeRaw(sql: string): Promise<void>;
 }
 /** Per-repository sync options, typed to the repo's field names. */
 interface RepoSyncConfig<F extends string = string> {
@@ -202,7 +210,7 @@ interface GenerateDDLConfig<M = Record<string, any>> {
 /**
  * HTTP Basic Auth configuration for the sync admin.
  */
-interface SyncAdminBasicAuth {
+interface adminsyncBasicAuth {
     type: "basic";
     /** Realm displayed in the browser login dialog */
     realm?: string;
@@ -212,7 +220,7 @@ interface SyncAdminBasicAuth {
 /**
  * Feature flags controlling which sync admin endpoints are enabled.
  */
-interface SyncAdminFeaturesFlag {
+interface adminsyncFeaturesFlag {
     /** Show pending queue state (default: false) */
     viewQueue?: boolean;
     /** Allow force-syncing an entire collection (default: false) */
@@ -227,13 +235,13 @@ interface SyncAdminFeaturesFlag {
  * When provided in `FirestoreSyncConfig.admin`, an `onRequest` Cloud Function
  * handler is created and added to `sync.functions`.
  */
-interface SyncAdminConfig {
+interface adminsyncConfig {
     /** Authentication guard — HTTP Basic Auth or custom middleware function */
-    auth?: SyncAdminBasicAuth | ((req: any, res: any, next: () => void) => void | Promise<void>);
+    auth?: adminsyncBasicAuth | ((req: any, res: any, next: () => void) => void | Promise<void>);
     /** Base URL path (default: "/sync-admin") */
     basePath?: string;
     /** Feature flags controlling which endpoints are enabled */
-    featuresFlag?: SyncAdminFeaturesFlag;
+    featuresFlag?: adminsyncFeaturesFlag;
     /**
      * `onRequest` from `firebase-functions/https` (or `firebase-functions/v2/https`).
      * When provided, the admin handler is automatically wrapped as a Cloud Function.
@@ -248,10 +256,21 @@ interface SyncAdminConfig {
 }
 /** Options for `createFirestoreSync()` — the unified wrapper. */
 interface FirestoreSyncConfig<M = Record<string, any>> {
-    /** External dependencies — all Firebase/PubSub modules */
-    deps: SyncDeps;
-    /** SQL adapter to flush data to */
-    adapter: SqlAdapter;
+    /**
+     * External dependencies — all Firebase/PubSub modules.
+     * `pubsub` can be a factory `() => PubSub` for lazy initialization
+     * (avoids creating gRPC channels at module-load time for functions that
+     * don't need PubSub, e.g. the admin or CRUD servers).
+     */
+    deps: Omit<SyncDeps, "pubsub"> & {
+        pubsub: OrFactory<PubSubClientDep>;
+    };
+    /**
+     * SQL adapter to flush data to.
+     * Can be a factory `() => adapter` for lazy initialization
+     * (avoids connecting to BigQuery / SQL at module-load time).
+     */
+    adapter: OrFactory<SqlAdapter>;
     /** PubSub topic name prefix (topics will be `{prefix}-{repoName}`) */
     topicPrefix?: string;
     /** Max rows per flush batch (default: 100) */
@@ -261,13 +280,13 @@ interface FirestoreSyncConfig<M = Record<string, any>> {
     /** Auto-create/migrate tables on first event (default: false) */
     autoMigrate?: boolean;
     /**
-     * Optional sync admin endpoint. When provided, a `syncAdmin` handler is
+     * Optional sync admin endpoint. When provided, a `adminsync` handler is
      * added to `sync.functions` exposing health-check, force-sync, and queue
      * inspection endpoints behind authentication.
      */
-    admin?: SyncAdminConfig;
+    admin?: adminsyncConfig;
     /** Per-repo overrides (shared between triggers and worker) */
     repos?: TypedRepoSyncConfigs<M>;
 }
 
-export type { FirestoreSyncConfig as F, GenerateDDLConfig as G, LogicalType as L, PubSubClientDep as P, RepoSyncConfig as R, SqlDialect as S, SqlColumn as a, SqlTableDef as b, SqlAdapter as c, SyncEvent as d, SyncWorkerConfig as e, SyncTriggersConfig as f, SyncAdminConfig as g, SyncOperation as h, SyncDeps as i, FirestoreTriggersDep as j, PubSubHandlerDep as k, SyncAdminBasicAuth as l, SyncAdminFeaturesFlag as m };
+export type { FirestoreSyncConfig as F, GenerateDDLConfig as G, LogicalType as L, OrFactory as O, PubSubClientDep as P, RepoSyncConfig as R, SqlAdapter as S, SyncEvent as a, adminsyncConfig as b, SqlDialect as c, SqlColumn as d, SqlTableDef as e, SyncTriggersConfig as f, SyncWorkerConfig as g, FirestoreTriggersDep as h, PubSubHandlerDep as i, SyncDeps as j, SyncOperation as k, adminsyncBasicAuth as l, adminsyncFeaturesFlag as m };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpdjs/firestore-repo-service",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "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",