@lpdjs/firestore-repo-service 2.0.1 → 2.1.0

package/README.md

@@ -22,6 +22,8 @@ Un service de repository type-safe pour Firestore avec génération automatique
 - 🔄 **Transactions** : Opérations transactionnelles type-safe
 - 🔗 **Relations** : Populate avec select typé (champs projetés)
 - 📄 **Pagination** : Curseurs, include avec relations, select
+- 🔄 **Firestore → SQL Sync** : Réplication vers BigQuery via Pub/Sub avec admin UI
+- 🖥️ **Serveur Admin** : UI admin auto-générée avec formulaires Zod, filtrage, navigation de relations
 
 ## 📦 Installation
 
@@ -594,6 +596,87 @@ for (const post of page.data) {
 }
 ```
 
+## 🔄 Firestore → SQL Sync
+
+Répliquez automatiquement vos collections Firestore vers BigQuery (ou toute base SQL) via Cloud Pub/Sub.
+
+### Architecture
+
+```
+Firestore Triggers → Cloud Pub/Sub → Worker → BigQuery
+```
+
+### Démarrage rapide
+
+```typescript
+import { createFirestoreSync } from "@lpdjs/firestore-repo-service/sync";
+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, {
+  deps: { firestoreTriggers, pubsubHandler, pubsub: new PubSub() },
+  adapter: new BigQueryAdapter({
+    bigquery: new BigQuery({ projectId: "my-project" }),
+    datasetId: "firestore_sync",
+  }),
+  topicPrefix: "firestore-sync",
+  autoMigrate: true,
+  admin: {
+    auth: { type: "basic", username: "admin", password: "secret" },
+    featuresFlag: {
+      healthCheck: true,
+      manualSync: true,
+      viewQueue: true,
+      configCheck: true,
+    },
+  },
+  repos: {
+    users: { tableName: "users", columnMap: { docId: "user_id" } },
+    posts: { columnMap: { docId: "post_id" } },
+    // Collection groups nécessitent triggerPath
+    comments: { triggerPath: "posts/{postId}/comments/{docId}" },
+  },
+});
+
+// Export des Cloud Functions
+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,
+} = sync.functions;
+
+// Admin (optionnel)
+export const syncAdmin = onRequest(sync.adminHandler!);
+```
+
+### Sync Admin
+
+L'endpoint admin fournit :
+
+- **Health Check** : Compare le schéma attendu (Zod) vs les colonnes BigQuery réelles
+- **Force Sync** : Re-synchronise tous les documents d'une collection
+- **View Queues** : Inspecte les éléments en attente
+- **Config Check** : Vérifie APIs GCP, topics, tables — avec commandes `gcloud` pour corriger
+
+### Adaptateur personnalisé
+
+Implémentez l'interface `SqlAdapter` pour d'autres bases de données :
+
+```typescript
+import type { SqlAdapter } from "@lpdjs/firestore-repo-service/sync";
+
+class MyAdapter implements SqlAdapter {
+  // tableExists, getTableColumns, createTable, insertRows,
+  // upsertRows, deleteRows, executeRaw
+}
+```
+
+📚 **Documentation complète** : [frs.lpdjs.fr/guide/sync](https://frs.lpdjs.fr/guide/sync)
+
 ## 🔧 Types exportés
 
 ```typescript
@@ -616,6 +699,16 @@ import type {
   PaginationWithIncludeOptions,
   PaginationWithIncludeOptionsTyped,
 } from "@lpdjs/firestore-repo-service";
+
+// Sync types
+import type {
+  FirestoreSyncConfig,
+  SqlAdapter,
+  SqlColumn,
+  SqlTableDef,
+  RepoSyncConfig,
+  SyncAdminConfig,
+} from "@lpdjs/firestore-repo-service/sync";
 ```
 
 ## 🧪 Tests avec l'émulateur

package/dist/index-28xuzvxq.d.cts

@@ -0,0 +1,530 @@
+import { z } from 'zod';
+import { C as ConfiguredRepository, R as RepositoryConfig, F as FieldPath, n as FieldRole } from './types-C0YpUzog.cjs';
+
+/**
+ * Minimal zero-dependency HTTP router for Firebase Functions.
+ * Compatible with any Express-like (req, res) handler.
+ *
+ * Supports:
+ *  - Named path parameters  (e.g. "/repos/:name/:id")
+ *  - GET, POST, DELETE methods
+ *  - Global middleware (before each route)
+ *  - 404 / error fallbacks
+ *
+ * @example
+ * ```typescript
+ * import { MiniRouter } from "@lpdjs/firestore-repo-service/servers/admin";
+ *
+ * // Create router
+ * const router = new MiniRouter();
+ *
+ * // Add global middleware (executed before every route)
+ * router.use(async (req, res, next) => {
+ *   console.log(`${req.method} ${req.url}`);
+ *   await next();
+ * });
+ *
+ * // Auth middleware
+ * router.use((req, res, next) => {
+ *   if (!req.headers?.authorization) {
+ *     res.status(401).send("Unauthorized");
+ *     return;
+ *   }
+ *   next();
+ * });
+ *
+ * // Define routes with path parameters
+ * router.get("/users", async (req, res) => {
+ *   res.json({ users: await getAllUsers() });
+ * });
+ *
+ * router.get("/users/:id", async (req, res) => {
+ *   const user = await getUser(req.params.id); // Access path params
+ *   if (!user) {
+ *     res.status(404).send("User not found");
+ *     return;
+ *   }
+ *   res.json(user);
+ * });
+ *
+ * router.post("/users", async (req, res) => {
+ *   const user = await createUser(req.body);
+ *   res.status(201).json(user);
+ * });
+ *
+ * router.delete("/users/:id", async (req, res) => {
+ *   await deleteUser(req.params.id);
+ *   res.status(204).end();
+ * });
+ *
+ * // Custom 404 handler
+ * router.onNotFound((req, res) => {
+ *   res.status(404).json({ error: "Route not found", path: req.url });
+ * });
+ *
+ * // Custom error handler
+ * router.onError((err, req, res) => {
+ *   console.error("Error:", err);
+ *   res.status(500).json({ error: "Internal server error" });
+ * });
+ *
+ * // Use with Firebase Functions
+ * export const api = onRequest(async (req, res) => {
+ *   await router.handle(req, res);
+ * });
+ * ```
+ */
+type AnyReq = {
+    method?: string;
+    url?: string;
+    /** Express originalUrl — preserved before any router stripping, contains the full path including the Firebase Functions prefix */
+    originalUrl?: string;
+    path?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    query?: Record<string, string | string[] | undefined>;
+};
+type AnyRes = {
+    status: (code: number) => AnyRes;
+    set: (key: string, value: string) => AnyRes;
+    send: (body: string) => void;
+    json: (body: unknown) => void;
+    end: () => void;
+};
+type RouteParams = Record<string, string>;
+type RouteHandler = (req: AnyReq & {
+    params: RouteParams;
+}, res: AnyRes) => void | Promise<void>;
+type Middleware = (req: AnyReq & {
+    params: RouteParams;
+}, res: AnyRes, next: () => void | Promise<void>) => void | Promise<void>;
+declare class MiniRouter {
+    private routes;
+    private middlewares;
+    private notFoundHandler;
+    private errorHandler;
+    use(middleware: Middleware): this;
+    get(path: string, handler: RouteHandler): this;
+    post(path: string, handler: RouteHandler): this;
+    put(path: string, handler: RouteHandler): this;
+    patch(path: string, handler: RouteHandler): this;
+    delete(path: string, handler: RouteHandler): this;
+    onNotFound(handler: RouteHandler): this;
+    onError(handler: (err: unknown, req: AnyReq, res: AnyRes) => void): this;
+    private addRoute;
+    handle(req: AnyReq, res: AnyRes): Promise<void>;
+    private runMiddlewareChain;
+}
+
+interface PageOptions {
+    title: string;
+    breadcrumb?: {
+        label: string;
+        href?: string;
+    }[];
+    flash?: {
+        type: "success" | "error";
+        message: string;
+    };
+    basePath?: string;
+}
+/** Firestore WHERE operator */
+type WhereOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "array-contains" | "array-contains-any";
+/** One active filter — serialized in URL as fv_{field} + fo_{field} */
+interface FilterState {
+    field: string;
+    op: WhereOp;
+    value: string;
+}
+/** Per-column metadata used to render appropriate filter inputs/operators */
+interface ColumnMeta {
+    name: string;
+    /** Innermost Zod type name, e.g. "ZodString", "ZodNumber" */
+    zodType: string;
+}
+/** Active sort state for the list view */
+interface SortState {
+    field: string;
+    dir: "asc" | "desc";
+}
+/**
+ * Metadata for one relational action column appended to the list table.
+ * Each entry produces a dedicated button column (not a cell replacement).
+ */
+interface RelationalFieldMeta {
+    /** Field in this document whose value is used to build the link */
+    key: string;
+    /** Column header label, e.g. "Posts" or "Author" */
+    column: string;
+    /** Name of the target repository in the admin registry */
+    targetRepo: string;
+    /** Field name on the target repo used for the lookup */
+    targetKey: string;
+    /**
+     * - "one"  → doc[key] = docId on the target → link to edit page
+     * - "many" → doc[key] = filter value on the target → link to filtered list
+     */
+    type: "one" | "many";
+}
+
+/**
+ * HTTP route handlers for the admin ORM server.
+ * Each handler corresponds to a URL pattern registered in the router.
+ *
+ * Routes:
+ *   GET  /                       → dashboard   GET  /:repoName              → document list (paginated)
+ *   GET  /:repoName/create       → create form
+ *   POST /:repoName/create       → submit create
+ *   GET  /:repoName/:id/edit     → edit form (pre-filled)
+ *   POST /:repoName/:id/edit     → submit update
+ *   POST /:repoName/:id/delete   → delete document
+ */
+
+interface AdminRepoEntry {
+    name: string;
+    path: string;
+    repo: ConfiguredRepository<RepositoryConfig<any, any, any, any, any, any, any, any, any, any>>;
+    schema: z.ZodObject<any>;
+    /** document key field name (default: "docId") */
+    documentKey?: string;
+    /** Field name that stores the full Firestore document path (e.g. "documentPath") */
+    pathKey?: string;
+    /** Whether this repo is a collection group (subcollection) */
+    isGroup?: boolean;
+    /** Parent key field names needed to build a subcollection document ref (auto-detected from refCb) */
+    parentKeys?: string[];
+    /** Field name for the creation timestamp (auto-set on create) */
+    createdKey?: string;
+    /** List of columns to display in the table (defaults to schema keys) */
+    listColumns?: string[];
+    /** Page size for list view (default: 25) */
+    pageSize?: number;
+    /** Fields exposed in the filter bar (defaults to all schema keys) */
+    filterableFields?: string[];
+    /** Fields shown in the edit form (defaults to all schema fields if unset) */
+    mutableFields?: string[];
+    /** Fields shown in the create form (defaults to all schema fields if unset) */
+    createFields?: string[];
+    /** Whether delete is allowed (default: false) */
+    allowDelete?: boolean;
+    /**
+     * Fields that link to another repository.
+     * Populated automatically from the repo's relationalKeys.
+     */
+    relationalMeta?: RelationalFieldMeta[];
+}
+type RepoRegistry = Record<string, AdminRepoEntry>;
+
+/**
+ * @module servers/admin
+ *
+ * Creates a static ORM admin interface served as a Firebase HTTPS function.
+ *
+ * Features:
+ *  - Dashboard listing all registered repositories
+ *  - Document list with cursor-based pagination
+ *  - Create / Edit / Delete forms generated from Zod schemas
+ *  - Forms map **exactly** to the repository model type
+ *  - Zero JavaScript framework — plain HTML + inline CSS + vanilla JS
+ *  - Body parsing for `application/x-www-form-urlencoded` (default HTML forms)
+ *    and `application/json` (API clients)
+ *
+ * @example
+ * ```ts
+ * import * as functions from "firebase-functions";
+ * import { z } from "zod";
+ * import { createAdminServer } from "@lpdjs/firestore-repo-service/servers/admin";
+ *
+ * const postSchema = z.object({
+ *   title:    z.string().min(1),
+ *   content:  z.string(),
+ *   status:   z.enum(["draft", "published"]),
+ *   authorId: z.string(),
+ * });
+ *
+ * export const adminApp = functions.https.onRequest(
+ *   createAdminServer({
+ *     basePath: "/admin",
+ *     repos: {
+ *       posts: { repo: repos.posts, schema: postSchema, path: "posts" },
+ *     },
+ *   })
+ * );
+ * ```
+ */
+
+/**
+ * Extracts the model type `T` from a `ConfiguredRepository`.
+ * @internal
+ */
+type RepoModelType<TRepo> = TRepo extends ConfiguredRepository<RepositoryConfig<infer T, any, any, any, any, any, any, any, any, any>> ? T : never;
+/**
+ * Configuration for a single repository in the admin server.
+ *
+ * @template TRepo - The `ConfiguredRepository` type; used to derive typed field names.
+ *
+ * If the repository was created with `createRepositoryConfig(schema)(config)`,
+ * the `schema` field is optional — it is auto-detected from the repo.
+ * Otherwise, pass `schema` explicitly.
+ *
+ * @example
+ * ```ts
+ * posts: {
+ *   repo: repos.posts,
+ *   fieldsConfig: {
+ *     title:   ["create", "mutable", "filterable"],
+ *     content: ["create", "mutable"],
+ *     status:  ["create", "filterable"],
+ *   },
+ *   allowDelete: true,
+ * }
+ * ```
+ */
+interface AdminRepoConfig<TRepo extends ConfiguredRepository<any> = ConfiguredRepository<any>> {
+    /** The configured repository instance. Drives type inference for all other fields. */
+    repo: TRepo;
+    /**
+     * Zod schema — optional when the repo was created with `createRepositoryConfig(schema)`.
+     * Pass explicitly for repos created with the legacy `createRepositoryConfig<T>()` form.
+     */
+    schema?: z.ZodObject<any>;
+    /** Firestore collection path (for display only) */
+    path: string;
+    /** Key used to identify documents (default: "docId") */
+    documentKey?: string;
+    /** Columns to display in the list view (default: all schema keys) */
+    listColumns?: string[];
+    /** Number of documents per page in the list view (default: 25) */
+    pageSize?: number;
+    /**
+     * Per-field role configuration.
+     * Each key is a model field (with autocomplete); the value is an array of roles.
+     *
+     * Roles:
+     * - `"create"` — field is shown in the create form
+     * - `"mutable"` — field is shown in the edit form
+     * - `"filterable"` — field is shown in the filter bar
+     *
+     * If omitted, all schema fields are shown in all contexts.
+     *
+     * @example
+     * ```ts
+     * fieldsConfig: {
+     *   title:   ["create", "mutable", "filterable"],
+     *   content: ["create", "mutable"],
+     *   status:  ["create", "filterable"],
+     * }
+     * ```
+     */
+    fieldsConfig?: Partial<Record<FieldPath<RepoModelType<TRepo>>, readonly FieldRole[]>>;
+    /**
+     * Whether to show the delete button in the list view.
+     * Default: false — delete is disabled unless explicitly set to true.
+     */
+    allowDelete?: boolean;
+    /**
+     * Relational action columns appended to the list table.
+     * Each entry adds a dedicated button that navigates to the linked repository.
+     *
+     * - **type "one"** (e.g. `userId` on a post) → button links to the target
+     *   document edit page: `/{targetRepo}/{value}/edit`
+     * - **type "many"** (e.g. `docId` on a user) → button links to the target
+     *   repo list filtered by value: `/{targetRepo}?fv_{targetKey}={value}`
+     *
+     * @example
+     * ```ts
+     * users: {
+     *   repo: repos.users,
+     *   relationalFields: [
+     *     { key: "docId", column: "Posts" },     // many → list of posts by this user
+     *   ]
+     * }
+     * posts: {
+     *   repo: repos.posts,
+     *   relationalFields: [
+     *     { key: "userId", column: "Author" },   // one → edit page of the user
+     *   ]
+     * }
+     * ```
+     */
+    relationalFields?: {
+        key: keyof RepoModelType<TRepo> & string;
+        column: string;
+    }[];
+}
+/**
+ * HTTP Basic Auth configuration.
+ * The browser will show a native login dialog.
+ */
+interface BasicAuthConfig {
+    type: "basic";
+    /** Realm displayed in the browser login dialog */
+    realm?: string;
+    username: string;
+    password: string;
+}
+/**
+ * Options for `createAdminServer`.
+ *
+ * Made generic so TypeScript can infer the model type of each repo entry
+ * and provide autocomplete + type-checking on `fieldsConfig`.
+ *
+ * @template TRepos - Shape of the repos map (inferred automatically at the call site)
+ */
+interface AdminServerOptions<TRepos extends Record<string, ConfiguredRepository<any>> = Record<string, ConfiguredRepository<any>>> {
+    /**
+     * Base URL path of the function (e.g. "/admin").
+     * Must match the path where the Firebase Function is mounted.
+     * Default: "/"
+     */
+    basePath?: string;
+    /**
+     * Repository entries keyed by a display name.
+     * TypeScript infers the model type from each `repo` field,
+     * so `fieldsConfig` keys are typed to that model's field paths.
+     *
+     * @example
+     * ```ts
+     * repos: {
+     *   posts: {
+     *     repo: repos.posts,
+     *     fieldsConfig: {
+     *       title:   ["create", "mutable", "filterable"],
+     *       content: ["create", "mutable"],
+     *       status:  ["create", "filterable"],
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    repos: {
+        [K in keyof TRepos]: AdminRepoConfig<TRepos[K]>;
+    };
+    /** Whether to parse URL-encoded bodies. Default: true. */
+    parseBody?: boolean;
+    /**
+     * Authentication guard executed before every request.
+     * - Pass a `BasicAuthConfig` to enable HTTP Basic Auth.
+     * - Pass a `Middleware` function for custom auth logic.
+     */
+    auth?: BasicAuthConfig | Middleware;
+    /**
+     * Additional middleware functions executed after auth, before route handlers.
+     */
+    middleware?: Middleware[];
+}
+/**
+ * Creates an Express-compatible request handler for the admin ORM UI.
+ * Generates a complete admin interface with dashboard, lists, and CRUD forms.
+ *
+ * @template TRepos - Shape of the repos map (inferred automatically)
+ * @param options - Admin server configuration
+ * @returns Express-compatible request handler for Firebase Functions
+ *
+ * @example
+ * ```typescript
+ * // Basic admin server
+ * import { onRequest } from "firebase-functions/https";
+ * import { createAdminServer } from "@lpdjs/firestore-repo-service/servers/admin";
+ *
+ * export const admin = onRequest(
+ *   createAdminServer({
+ *     basePath: "/admin",
+ *     repos: {
+ *       users: {
+ *         repo: repos.users,
+ *         path: "users",
+ *       },
+ *       posts: {
+ *         repo: repos.posts,
+ *         path: "posts",
+ *       },
+ *     },
+ *   })
+ * );
+ *
+ * // With HTTP Basic Auth
+ * export const admin = onRequest(
+ *   createAdminServer({
+ *     basePath: "/admin",
+ *     auth: {
+ *       type: "basic",
+ *       realm: "Admin Area",
+ *       username: "admin",
+ *       password: process.env.ADMIN_PASSWORD!,
+ *     },
+ *     repos: { ... },
+ *   })
+ * );
+ *
+ * // With custom auth middleware
+ * export const admin = onRequest(
+ *   createAdminServer({
+ *     auth: async (req, res, next) => {
+ *       const token = req.headers?.authorization?.replace("Bearer ", "");
+ *       if (!token || !(await verifyToken(token))) {
+ *         res.status(401).send("Unauthorized");
+ *         return;
+ *       }
+ *       next();
+ *     },
+ *     repos: { ... },
+ *   })
+ * );
+ *
+ * // Full configuration with all options
+ * export const admin = onRequest(
+ *   createAdminServer({
+ *     basePath: "/admin",
+ *     parseBody: true,                    // Parse URL-encoded bodies
+ *     auth: { type: "basic", username: "admin", password: "secret" },
+ *     middleware: [loggingMiddleware],    // Additional middleware
+ *     repos: {
+ *       posts: {
+ *         repo: repos.posts,
+ *         path: "posts",
+ *         documentKey: "docId",           // Field used as document ID
+ *         listColumns: ["title", "status", "createdAt"], // Columns in list
+ *         pageSize: 25,                   // Items per page in list
+ *         fieldsConfig: {
+ *           title:   ["create", "mutable", "filterable"],
+ *           content: ["create", "mutable"],
+ *           status:  ["create", "mutable", "filterable"],
+ *           userId:  ["filterable"],
+ *         },
+ *         allowDelete: true,              // Enable delete button
+ *         relationalFields: [             // Relation navigation buttons
+ *           { key: "userId", column: "Author" },    // Link to user
+ *           { key: "docId", column: "Comments" },   // Link to comments list
+ *         ],
+ *       },
+ *       users: {
+ *         repo: repos.users,
+ *         path: "users",
+ *         fieldsConfig: {
+ *           name:     ["create", "mutable"],
+ *           email:    ["create", "mutable", "filterable"],
+ *           isActive: ["mutable", "filterable"],
+ *         },
+ *         allowDelete: false,
+ *         relationalFields: [
+ *           { key: "docId", column: "Posts" },
+ *         ],
+ *       },
+ *     },
+ *   })
+ * );
+ *
+ * // Routes generated automatically:
+ * // GET  /admin/              → Dashboard (list of repos)
+ * // GET  /admin/:repo         → Document list with pagination
+ * // GET  /admin/:repo/create  → Create form
+ * // POST /admin/:repo/create  → Submit create
+ * // GET  /admin/:repo/:id/edit → Edit form
+ * // POST /admin/:repo/:id/edit → Submit edit
+ * // POST /admin/:repo/:id/delete → Delete document
+ * ```
+ */
+declare function createAdminServer<TRepos extends Record<string, ConfiguredRepository<any>>>(options: AdminServerOptions<TRepos>): (req: any, res: any) => Promise<void>;
+
+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 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 };