@lpdjs/firestore-repo-service 2.2.4 → 2.2.6

package/README.md

@@ -251,24 +251,50 @@ const users = await repos.users.query.by({
 });
 ```
 
-## Firestore → SQL Sync
+## Servers (admin UI · CRUD REST · Firestore → SQL sync)
 
-Replicate Firestore collections to BigQuery (or any SQL database) via Cloud Pub/Sub and Cloud Functions v2.
-
-```
-Firestore triggers → Pub/Sub → CF v2 worker → BigQuery MERGE
-```
+A single unified factory binds all servers to your repository registry. Per-repo `repo: …` is no longer needed — the registry key drives both the runtime binding and the inferred model type for `fieldsConfig` autocomplete.
 
 ```typescript
-import { createFirestoreSync } from "@lpdjs/firestore-repo-service/sync";
+import { createServers } from "@lpdjs/firestore-repo-service";
+import { onRequest } from "firebase-functions/v2/https";
 import { BigQueryAdapter } from "@lpdjs/firestore-repo-service/sync/bigquery";
 import { BigQuery } from "@google-cloud/bigquery";
 import { PubSub } from "@google-cloud/pubsub";
 import * as firestoreTriggers from "firebase-functions/v2/firestore";
 import * as pubsubHandler from "firebase-functions/v2/pubsub";
-import { onRequest } from "firebase-functions/v2/https";
 
-const sync = createFirestoreSync(repos, {
+const servers = createServers(repos, {
+  onRequest,
+  httpsOptions: { invoker: "public" },
+});
+
+// Admin UI — repo auto-injected from the key, fieldsConfig typed against the model
+export const admin = servers.admin({
+  basePath: "/admin",
+  auth: { type: "basic", username: "admin", password: "secret" },
+  repos: {
+    posts: {
+      path: "posts",
+      fieldsConfig: { title: ["create", "mutable"], status: ["filterable"] },
+      allowDelete: true,
+    },
+    users: { path: "users" },
+  },
+});
+
+// CRUD REST API
+export const api = servers.crud({
+  basePath: "/api",
+  repos: {
+    posts: { path: "posts", allowDelete: true },
+    users: { path: "users" },
+  },
+  openapi: { title: "My API", version: "1.0.0" },
+});
+
+// Firestore → BigQuery sync (triggers + worker + admin Cloud Functions)
+export const { functions } = servers.sync({
   deps: { firestoreTriggers, pubsubHandler, pubsub: new PubSub() },
   adapter: new BigQueryAdapter({
     bigquery: new BigQuery({ projectId: "my-project" }),
@@ -276,15 +302,7 @@ const sync = createFirestoreSync(repos, {
   }),
   topicPrefix: "firestore-sync",
   autoMigrate: true,
-  batchSize: 500,
-  flushIntervalMs: 10_000,
-  workerOptions: {
-    concurrency: 5,
-    maxInstances: 10,
-  },
   admin: {
-    onRequest,
-    httpsOptions: { invoker: "public" },
     auth: { type: "basic", username: "admin", password: "secret" },
     featuresFlag: { healthCheck: true, manualSync: true, viewQueue: true, configCheck: true },
   },
@@ -295,15 +313,18 @@ const sync = createFirestoreSync(repos, {
   },
 });
 
+// Spread Cloud Functions into your exports
 export const {
   users_onCreate, users_onUpdate, users_onDelete, sync_users,
   posts_onCreate, posts_onUpdate, posts_onDelete, sync_posts,
   comments_onCreate, comments_onUpdate, comments_onDelete, sync_comments,
   adminsync,
-} = sync.functions;
+} = functions;
 ```
 
-The admin endpoint (`/`) exposes a UI for health checks, force-sync, queue inspection, and GCP config verification.
+When `onRequest` is passed to `createServers`, `servers.admin()` and `servers.crud()` return ready-to-export Cloud Functions. Without it, they return raw HTTP handlers you can wrap yourself.
+
+The sync admin endpoint (`/`) exposes a UI for health checks, force-sync, queue inspection, and GCP config verification.
 
 For a custom SQL backend, implement the `SqlAdapter` interface:
 

package/dist/create-servers-D4-NGpKm.d.ts

@@ -0,0 +1,105 @@
+import { S as SyncQueue } from './queue-D_-aMf4H.js';
+import { F as FirestoreSyncConfig, S as SyncEvent } from './types-CX5AbZWV.js';
+import { O as OpenAPIDocument } from './openapi-B3P2F8op.js';
+import * as firebase_functions_v2_https from 'firebase-functions/v2/https';
+import { onRequest, HttpsOptions } from 'firebase-functions/v2/https';
+import { C as ConfiguredRepository, m as CrudServerOptions, l as CrudRepoConfig } from './types-Z9Qy8Xmx.js';
+import { b as AdminServerOptions, A as AdminRepoConfig } from './index-Cvip2Sgt.js';
+
+/** Per-repo admin config with `repo` omitted (auto-bound from the registry key). */
+type BoundAdminRepoConfig<TRepo extends ConfiguredRepository<any>> = Omit<AdminRepoConfig<TRepo>, "repo">;
+/** Per-repo CRUD config with `repo` omitted (auto-bound from the registry key). */
+type BoundCrudRepoConfig<TRepo extends ConfiguredRepository<any>> = Omit<CrudRepoConfig<TRepo>, "repo">;
+/**
+ * Admin server options for the bound builder.
+ * `repos` becomes a partial record so callers can expose a subset of the
+ * underlying registry, and each entry omits `repo` (injected from the key).
+ */
+interface BoundAdminServerOptions<TRepos extends Record<string, ConfiguredRepository<any>>> extends Omit<AdminServerOptions<TRepos>, "repos"> {
+    repos: {
+        [K in keyof TRepos]?: BoundAdminRepoConfig<TRepos[K]>;
+    };
+}
+/** CRUD server options for the bound builder. */
+interface BoundCrudServerOptions<TRepos extends Record<string, ConfiguredRepository<any>>> extends Omit<CrudServerOptions<TRepos>, "repos"> {
+    repos: {
+        [K in keyof TRepos]?: BoundCrudRepoConfig<TRepos[K]>;
+    };
+}
+/**
+ * Sync config for the bound builder — identical to `FirestoreSyncConfig`
+ * but the top-level `repoMapping` argument is supplied by `createServers`.
+ */
+type BoundFirestoreSyncConfig<TRepos extends Record<string, any>> = FirestoreSyncConfig<TRepos>;
+/** Optional dependencies shared across every server. */
+interface CreateServersDeps {
+    /**
+     * `onRequest` from `firebase-functions/v2/https`. When provided, the
+     * admin/CRUD builders return a ready-to-export Cloud Function instead of
+     * the raw handler. Also forwarded to the sync admin (so the bundled
+     * `adminsync` Cloud Function is generated automatically).
+     */
+    onRequest?: typeof onRequest;
+    /**
+     * Default `httpsOptions` applied to every server. Per-server options
+     * override these defaults.
+     */
+    httpsOptions?: HttpsOptions;
+}
+/**
+ * Pre-binds a repository mapping to all server builders.
+ *
+ * @template TRepos - Repository registry; inferred at the call site.
+ * @param repos - The repository mapping (e.g. result of `createRepositoryMapping`).
+ * @param deps  - Optional shared deps (notably `onRequest` for auto-wrapping).
+ *
+ * @example
+ * ```ts
+ * import { onRequest } from "firebase-functions/v2/https";
+ * import { createServers } from "@lpdjs/firestore-repo-service/servers";
+ *
+ * const servers = createServers(repos, { onRequest });
+ *
+ * export const admin = servers.admin({
+ *   basePath: "/admin",
+ *   repos: {
+ *     posts: { path: "posts", allowDelete: true },
+ *     users: { path: "users" },
+ *   },
+ * });
+ * ```
+ */
+declare function createServers<TRepos extends Record<string, ConfiguredRepository<any>>>(repos: TRepos, deps?: CreateServersDeps): {
+    /**
+     * Build the admin UI handler with `repo` auto-injected from each registry key.
+     * Returns a Cloud Function when `onRequest` was passed to `createServers`,
+     * otherwise the raw HTTP handler.
+     */
+    admin(options: BoundAdminServerOptions<TRepos>): firebase_functions_v2_https.HttpsFunction | (((req: any, res: any) => Promise<void>) & {
+        httpsOptions?: HttpsOptions;
+    });
+    /**
+     * Build the CRUD REST API handler with `repo` auto-injected from each
+     * registry key. Returns a Cloud Function when `onRequest` was passed to
+     * `createServers`, otherwise the raw HTTP handler (which still exposes
+     * `.spec()` and `.httpsOptions` on the raw form).
+     */
+    crud(options: BoundCrudServerOptions<TRepos>): firebase_functions_v2_https.HttpsFunction | (((req: any, res: any) => Promise<void>) & {
+        spec: () => OpenAPIDocument;
+        httpsOptions?: HttpsOptions;
+    });
+    /**
+     * Build the Firestore→SQL sync pipeline using the bound registry.
+     * Forwards the shared `onRequest` to the sync admin config so the
+     * bundled `adminsync` Cloud Function is auto-generated.
+     */
+    sync(config: BoundFirestoreSyncConfig<TRepos>): {
+        functions: Record<string, any>;
+        adminHandler: ((req: any, res: any) => Promise<void>) | null;
+        handleMessage: (event: SyncEvent) => Promise<void>;
+        queues: Map<string, SyncQueue>;
+        shutdown: () => Promise<void>;
+    };
+};
+
+export { type BoundAdminRepoConfig as B, type CreateServersDeps as C, type BoundAdminServerOptions as a, type BoundCrudRepoConfig as b, createServers as c, type BoundCrudServerOptions as d, type BoundFirestoreSyncConfig as e };

package/dist/create-servers-DmggzSb3.d.cts

@@ -0,0 +1,105 @@
+import { S as SyncQueue } from './queue-Dk1Ezhkf.cjs';
+import { F as FirestoreSyncConfig, S as SyncEvent } from './types-CX5AbZWV.cjs';
+import { O as OpenAPIDocument } from './openapi-UJJ1aCFk.cjs';
+import * as firebase_functions_v2_https from 'firebase-functions/v2/https';
+import { onRequest, HttpsOptions } from 'firebase-functions/v2/https';
+import { C as ConfiguredRepository, m as CrudServerOptions, l as CrudRepoConfig } from './types-Z9Qy8Xmx.cjs';
+import { b as AdminServerOptions, A as AdminRepoConfig } from './index-DpD4DEqH.cjs';
+
+/** Per-repo admin config with `repo` omitted (auto-bound from the registry key). */
+type BoundAdminRepoConfig<TRepo extends ConfiguredRepository<any>> = Omit<AdminRepoConfig<TRepo>, "repo">;
+/** Per-repo CRUD config with `repo` omitted (auto-bound from the registry key). */
+type BoundCrudRepoConfig<TRepo extends ConfiguredRepository<any>> = Omit<CrudRepoConfig<TRepo>, "repo">;
+/**
+ * Admin server options for the bound builder.
+ * `repos` becomes a partial record so callers can expose a subset of the
+ * underlying registry, and each entry omits `repo` (injected from the key).
+ */
+interface BoundAdminServerOptions<TRepos extends Record<string, ConfiguredRepository<any>>> extends Omit<AdminServerOptions<TRepos>, "repos"> {
+    repos: {
+        [K in keyof TRepos]?: BoundAdminRepoConfig<TRepos[K]>;
+    };
+}
+/** CRUD server options for the bound builder. */
+interface BoundCrudServerOptions<TRepos extends Record<string, ConfiguredRepository<any>>> extends Omit<CrudServerOptions<TRepos>, "repos"> {
+    repos: {
+        [K in keyof TRepos]?: BoundCrudRepoConfig<TRepos[K]>;
+    };
+}
+/**
+ * Sync config for the bound builder — identical to `FirestoreSyncConfig`
+ * but the top-level `repoMapping` argument is supplied by `createServers`.
+ */
+type BoundFirestoreSyncConfig<TRepos extends Record<string, any>> = FirestoreSyncConfig<TRepos>;
+/** Optional dependencies shared across every server. */
+interface CreateServersDeps {
+    /**
+     * `onRequest` from `firebase-functions/v2/https`. When provided, the
+     * admin/CRUD builders return a ready-to-export Cloud Function instead of
+     * the raw handler. Also forwarded to the sync admin (so the bundled
+     * `adminsync` Cloud Function is generated automatically).
+     */
+    onRequest?: typeof onRequest;
+    /**
+     * Default `httpsOptions` applied to every server. Per-server options
+     * override these defaults.
+     */
+    httpsOptions?: HttpsOptions;
+}
+/**
+ * Pre-binds a repository mapping to all server builders.
+ *
+ * @template TRepos - Repository registry; inferred at the call site.
+ * @param repos - The repository mapping (e.g. result of `createRepositoryMapping`).
+ * @param deps  - Optional shared deps (notably `onRequest` for auto-wrapping).
+ *
+ * @example
+ * ```ts
+ * import { onRequest } from "firebase-functions/v2/https";
+ * import { createServers } from "@lpdjs/firestore-repo-service/servers";
+ *
+ * const servers = createServers(repos, { onRequest });
+ *
+ * export const admin = servers.admin({
+ *   basePath: "/admin",
+ *   repos: {
+ *     posts: { path: "posts", allowDelete: true },
+ *     users: { path: "users" },
+ *   },
+ * });
+ * ```
+ */
+declare function createServers<TRepos extends Record<string, ConfiguredRepository<any>>>(repos: TRepos, deps?: CreateServersDeps): {
+    /**
+     * Build the admin UI handler with `repo` auto-injected from each registry key.
+     * Returns a Cloud Function when `onRequest` was passed to `createServers`,
+     * otherwise the raw HTTP handler.
+     */
+    admin(options: BoundAdminServerOptions<TRepos>): firebase_functions_v2_https.HttpsFunction | (((req: any, res: any) => Promise<void>) & {
+        httpsOptions?: HttpsOptions;
+    });
+    /**
+     * Build the CRUD REST API handler with `repo` auto-injected from each
+     * registry key. Returns a Cloud Function when `onRequest` was passed to
+     * `createServers`, otherwise the raw HTTP handler (which still exposes
+     * `.spec()` and `.httpsOptions` on the raw form).
+     */
+    crud(options: BoundCrudServerOptions<TRepos>): firebase_functions_v2_https.HttpsFunction | (((req: any, res: any) => Promise<void>) & {
+        spec: () => OpenAPIDocument;
+        httpsOptions?: HttpsOptions;
+    });
+    /**
+     * Build the Firestore→SQL sync pipeline using the bound registry.
+     * Forwards the shared `onRequest` to the sync admin config so the
+     * bundled `adminsync` Cloud Function is auto-generated.
+     */
+    sync(config: BoundFirestoreSyncConfig<TRepos>): {
+        functions: Record<string, any>;
+        adminHandler: ((req: any, res: any) => Promise<void>) | null;
+        handleMessage: (event: SyncEvent) => Promise<void>;
+        queues: Map<string, SyncQueue>;
+        shutdown: () => Promise<void>;
+    };
+};
+
+export { type BoundAdminRepoConfig as B, type CreateServersDeps as C, type BoundAdminServerOptions as a, type BoundCrudRepoConfig as b, createServers as c, type BoundCrudServerOptions as d, type BoundFirestoreSyncConfig as e };

package/dist/{index-BiWZwHS_.d.ts → index-Cvip2Sgt.d.ts}

@@ -562,4 +562,4 @@ declare function createAdminServer<TRepos extends Record<string, ConfiguredRepos
     httpsOptions?: HttpsOptions;
 };
 
-export { type AdminRepoConfig as A, type BasicAuthConfig as B, type ColumnMeta as C, type FilterState as F, MiniRouter as M, type PageOptions as P, type QueryError as Q, type RelationalFieldMeta as R, type SortState as S, type AdminRepoEntry as a, type AdminServerOptions as b, createAdminServer as c, type Middleware as d, type RepoRegistry as e, type RouteHandler as f };
+export { type AdminRepoConfig as A, type BasicAuthConfig as B, type ColumnMeta as C, type FilterState as F, MiniRouter as M, type PageOptions as P, type QueryError as Q, type RelationalFieldMeta as R, type SortState as S, type AdminRepoEntry as a, type AdminServerOptions as b, type Middleware as c, type RepoRegistry as d, type RouteHandler as e, createAdminServer as f };

package/dist/{index-B3-vAYx0.d.cts → index-DpD4DEqH.d.cts}

@@ -562,4 +562,4 @@ declare function createAdminServer<TRepos extends Record<string, ConfiguredRepos
     httpsOptions?: HttpsOptions;
 };
 
-export { type AdminRepoConfig as A, type BasicAuthConfig as B, type ColumnMeta as C, type FilterState as F, MiniRouter as M, type PageOptions as P, type QueryError as Q, type RelationalFieldMeta as R, type SortState as S, type AdminRepoEntry as a, type AdminServerOptions as b, createAdminServer as c, type Middleware as d, type RepoRegistry as e, type RouteHandler as f };
+export { type AdminRepoConfig as A, type BasicAuthConfig as B, type ColumnMeta as C, type FilterState as F, MiniRouter as M, type PageOptions as P, type QueryError as Q, type RelationalFieldMeta as R, type SortState as S, type AdminRepoEntry as a, type AdminServerOptions as b, type Middleware as c, type RepoRegistry as d, type RouteHandler as e, createAdminServer as f };