Initial Commit

packages/api-stack/api/api-plugin-site/src/service/db-port.ts

@@ -0,0 +1,47 @@
+/**
+ * Structural database port used by `SiteService` and
+ * `DomainResolverService`.
+ *
+ * The site plugin depends on the canonical `@suaveplan/db`
+ * `DatabaseAdapter.query` surface only — positional-binding strings via
+ * `$p0`, `$p1`, ... — plus the typed CRUD subset
+ * (`create` / `update`) exposed by `@suaveplan/surrealdb`'s
+ * `SurrealAdapter`. The genesis `DatabaseAdapter` interface owns only
+ * `query` / `execute`, so we declare the typed-CRUD surface here as a
+ * structural extension that real `SurrealAdapter` instances satisfy.
+ *
+ * Defining the port here decouples production wiring (which goes
+ * through `ServiceRegistry["db"]` typed as `SurrealAdapter`) from tests
+ * (which can supply any object conforming to this shape). No casts at
+ * the call site — the service constructor accepts this port directly.
+ */
+export interface SiteDb {
+    /**
+     * Execute a positional-binding SurQL statement. Inputs are bound as
+     * `$p0`, `$p1`, ... via `paramsToRecord` in the SurrealAdapter
+     * adapter; consumers of this port write the SurQL accordingly.
+     */
+    query<T = Record<string, unknown>>(
+        sql: string,
+        params?: readonly unknown[]
+    ): Promise<T[]>;
+
+    /**
+     * Typed CRUD create — `SurrealAdapter.create`. Returns the created
+     * record with its assigned id.
+     */
+    create<T extends Record<string, unknown>>(
+        table: string,
+        data: T
+    ): Promise<T & { id: string }>;
+
+    /**
+     * Typed CRUD update — `SurrealAdapter.update`. Returns the updated
+     * record, or `null` when no row matched.
+     */
+    update<T extends Record<string, unknown>>(
+        table: string,
+        id: string,
+        data: Partial<T>
+    ): Promise<T | null>;
+}