@palbase/backend 23.0.0 → 24.0.0

package/dist/{index-E7OscPJT.d.cts → index-DRFxf07H.d.cts}

@@ -1,8 +1,8 @@
 import { Buckets, BucketTypes } from './stack.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, T as TxPlanBody, f as TxPlanResponse } from './endpoint-i8TTCohk.cjs';
-import { E as EnvTypedDatabase } from './index-Bmvx1EvJ.cjs';
-import { R as RouteMeta } from './registry-C3H2uPeZ.cjs';
+import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse, A as AuthSpec } from './endpoint-CcQ1a36a.cjs';
+import { E as EnvTypedDatabase } from './index-D-4-PNuQ.cjs';
+import { R as RouteMeta } from './registry-1X-skBNu.cjs';
 
 /**
  * runtime.ts — request-scoped service singletons.
@@ -112,6 +112,72 @@ declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
  * process-global fallback (dev-server / tests). NOT part of the public
  * author-facing API — used by the runtime and the singleton Proxies. */
 declare function __getRuntime(): RuntimeServices;
+/** A lifecycle hook. Sync or async; the runtime awaits what it returns. */
+type LifecycleHook = () => void | Promise<void>;
+/** Runs one release's shutdown hooks. Handed back by {@link __runStartHooks}
+ * and called by the engine's `app.shutdown()`. Idempotent. */
+type ShutdownRunner = () => Promise<void>;
+/**
+ * Run `hook` ONCE while the application comes up, before it serves anything.
+ *
+ * Call it at MODULE SCOPE in a file the application imports — the same rule
+ * `defineDefaultAuth` and `@Controller` follow, and for the same reason: the
+ * declaration is claimed when the app boots, which is after module loading and
+ * before the first request. `name` is not decoration: a hook that throws is
+ * reported by that name and the boot is REFUSED, so it is what tells an
+ * operator which resource did not come up.
+ *
+ * There is no request scope yet, so the `Database`/`Secrets`/… singletons are
+ * NOT available inside a start hook. A secret is read from `process.env` here
+ * (the runtime mirrors the vault into it at boot).
+ *
+ * @example
+ * // resources/graph.ts
+ * import neo4j from "neo4j-driver";
+ * import { onStart, onShutdown } from "@palbase/backend";
+ *
+ * export let graph: Driver;
+ * onStart("graph", () => {
+ *   graph = neo4j.driver(process.env.NEO4J_URL!, neo4j.auth.basic("neo4j", process.env.NEO4J_PASSWORD!));
+ * });
+ * onShutdown("graph", () => graph.close());
+ */
+declare function onStart(name: string, hook: LifecycleHook): void;
+/**
+ * Run `hook` while the application shuts down — the place a pool opened in
+ * {@link onStart} is closed.
+ *
+ * Shutdown is BEST-EFFORT by design: a hook that throws is reported by name and
+ * the rest still run. A drain that abandoned the remaining hooks on the first
+ * failure would leak exactly what this exists to release, and the process is
+ * leaving anyway.
+ *
+ * Hooks run in REVERSE declaration order, so a resource is released before what
+ * it was built on.
+ */
+declare function onShutdown(name: string, hook: LifecycleHook): void;
+/**
+ * CLAIM what has been declared, run the start hooks, and hand back the runner
+ * for this release's shutdown hooks. Called by the engine's `createApp`; the
+ * `App.shutdown()` it builds calls what comes back. NOT part of the public
+ * author-facing API.
+ *
+ * IT CLAIMS RATHER THAN READS, which is what makes it correct in this runtime:
+ * a candidate release is loaded BESIDE the live one in one process
+ * (`v2/runtime/src/registry-scope.ts`), and both bundles append to the one
+ * shared slot above. If each app read the whole list, the live app's shutdown
+ * would close the candidate's pool and the candidate's would close the live
+ * app's. Taking the declarations leaves each app holding exactly its own.
+ *
+ * A start hook that throws REFUSES THE BOOT — with the hook's name in the
+ * message — after releasing whatever the earlier hooks already opened. Serving
+ * from a half-initialised app is the silence this whole surface replaces, and a
+ * boot that dies holding an open pool is the leak it replaces.
+ */
+declare function __runStartHooks(): Promise<ShutdownRunner>;
+/** Drop every declaration. For tests, which declare repeatedly in one process.
+ * NOT part of the public author-facing API. */
+declare function __resetLifecycleHooks(): void;
 /**
  * The project's own Postgres (pgx, schema `env_<envId>`).
  *
@@ -361,14 +427,79 @@ declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson:
 type LazyTransaction = ReturnType<typeof createLazyTransaction>;
 /** Either a live driver transaction or the lazy holder above. */
 type TxLike = SqlTx | LazyTransaction;
+/** What `findMany` accepts beside its filter: an ordering, a row ceiling and a
+ * page offset. All three used to require dropping to raw SQL, and the docs said
+ * so — which is how a tenant's controllers filled up with hand-written SELECTs. */
+interface FindManyOptions {
+    orderBy?: {
+        column: string;
+        direction?: "asc" | "desc";
+    };
+    limit?: number;
+    /** Rows to skip before the page starts. Only meaningful with `limit`, and
+     * refused without it — see `offsetClause`. */
+    offset?: number;
+}
 /** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
     query(sql: string, params?: unknown[]): Promise<Row[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * INSERT the row, or UPDATE it when it collides on `onConflict`.
+     *
+     * WHY IT IS AN OPERATION rather than a recipe. "Try the insert, catch the
+     * unique violation, update instead" does not work here: a request runs in ONE
+     * Postgres transaction, so the failed insert aborts it and every later
+     * statement answers `current transaction is aborted`. A tenant measured that
+     * as 7 of 8 concurrent requests returning 500, gave up on upsert, and had a
+     * trigger create the row instead — a workaround that needs a new trigger for
+     * every table with a unique row.
+     *
+     * The conflict columns are excluded from the SET list: they are what MATCHED,
+     * so writing them back is at best a no-op and at worst a surprise.
+     */
+    upsert(table: string, data: Row, opts: {
+        onConflict: readonly string[];
+    }): Promise<Row>;
     update(table: string, id: string, data: Row): Promise<Row | null>;
     delete(table: string, id: string): Promise<void>;
+    /**
+     * Update every row the filter matches, in ONE statement.
+     *
+     * The capability was already here and only reachable from inside a
+     * transaction plan (`tx.tables.x.updateWhere`, since 11.0.0). Outside it the
+     * only door was `update(id, …)`, so "mark every unapproved row in this
+     * household" was an N+1 loop or hand-written SQL — and hand-written SQL is
+     * where the typed surface and RLS both stop helping.
+     *
+     * The filter language is `findMany`'s, compiled by the same `compileWhere`:
+     * one filter language, or the two spellings drift.
+     *
+     * AN EMPTY FILTER IS REFUSED. `UPDATE … WHERE true` is a whole-table write,
+     * and the shape that produces it by accident — a filter object built from
+     * request input that happened to come back empty — is exactly the shape that
+     * should not silently succeed. Callers who mean every row say so with a
+     * predicate that is true for every row.
+     */
+    updateMany(table: string, where: Row, set: Row): Promise<Row[]>;
+    /**
+     * Delete every row the filter matches, in ONE statement; resolves to how
+     * many went. Same filter language, same empty-filter refusal as
+     * {@link updateMany} — and here the accident is worse.
+     */
+    deleteMany(table: string, where: Row): Promise<number>;
+    /**
+     * How many rows match — the half of pagination `limit`/`offset` cannot
+     * supply. Without it a page count is either a guess or "fetch everything and
+     * read .length", and the second one is the scale risk this surface exists to
+     * remove.
+     *
+     * An empty filter is legitimate HERE: counting a whole table is a read, and
+     * reads do not destroy anything.
+     */
+    count(table: string, where?: Row): Promise<number>;
     findById(table: string, id: string): Promise<Row | null>;
-    findMany(table: string, query?: Row): Promise<Row[]>;
+    findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -417,6 +548,21 @@ declare function createOps(tx: TxLike): {
      * tek SQL'de "id yok" ile "0 komşu" ayrılamazdı; +1 küçük turla id-yokluğu
      * adlandırılmış hataya çevrilir. Sonuç şekli search ile aynı (FR-015).
      */
+    /** D-021 (FR-027 DX): sayaçlar BAĞIMSIZ op'la — search'ün dizi-üstü
+     * `_facets` özelliği JSON.stringify'da kaybolur (dizi özelliği), tenant
+     * yanıtına koyunca sessizce yok olurdu. Ayrı dönüş ciddi bir sözleşmedir;
+     * search'teki alan geriye-uyum için DURUR. where + validity default'u
+     * sayaçlara da uygulanır (sayaç, kullanıcının gördüğü kümeyi anlatır). */
+    facets(table: string, params: {
+        facets: string[];
+        where?: Record<string, unknown>;
+        validity?: "all" | {
+            asOf: string;
+        };
+    }): Promise<Record<string, {
+        value: string | null;
+        count: number;
+    }[]>>;
     similar(table: string, id: string, opts?: {
         where?: Record<string, unknown>;
         limit?: number;
@@ -476,6 +622,24 @@ declare function createOps(tx: TxLike): {
     supersede(table: string, id: string, row: Row): Promise<Row>;
     /** A real SAVEPOINT inside the request's transaction. */
     transaction<T>(cb: (t: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
+     * rolls back only what that handle wrote and the request can keep writing.
+     *
+     * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
+     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * the ambient `Database` at the savepoint for the duration, and a request is
+     * concurrent with itself: `Promise.all([Database.insert(a),
+     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * back with it. Silent data loss, and the same interleaving this file already
+     * refuses for `asService()`. Passing the handle makes the boundary something
+     * you can see in the code that crosses it.
+     *
+     * Postgres, not us: the savepoint is released on success and rolled back on
+     * failure by the driver, so an aborted statement inside `fn` does not poison
+     * the surrounding transaction.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
      *
@@ -587,8 +751,11 @@ interface RouteEntry {
     instance: Record<string, (...args: unknown[]) => unknown>;
     /** `GET /todos/{id}` — stable, human-readable, used as the rate-limit key. */
     id: string;
-    /** The controller's `auth` default, if it declared one. */
-    controllerAuth: unknown;
+    /** The auth spec that applies when the route itself declares none —
+     * controller default ?? application default ?? `true`, resolved once at boot
+     * by `resolveEffectiveAuth`. `engine/index.ts` reconciles the route's own
+     * spec against it per request. */
+    controllerAuth: AuthSpec;
 }
 /**
  * Build the table from controller classes.
@@ -596,6 +763,9 @@ interface RouteEntry {
  * @throws when a class carries no routes — a controller that collected zero
  *   endpoints is the silent failure this whole runtime is built to refuse, and
  *   it must be loud at boot rather than a 404 in production.
+ * @throws when a class declares constructor parameters — the same class of
+ *   silence one level down (FR-010): nothing here has an argument to pass, so
+ *   the field would simply be `undefined` in production.
  */
 declare function buildRouteTable(controllers: readonly unknown[]): RouteEntry[];
 interface RouteMatch {
@@ -879,4 +1049,4 @@ interface App {
  */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, makeMemoryCache as G, matchRoute as H, quoteIdent as I, scrubSecrets as J, withTables as K, Log as L, type ModuleClients as M, Notifications as N, Realtime as R, Secrets as S, __getRuntime as _, Documents as a, type RequestStore as b, type RuntimeServices as c, Storage as d, __requestALS as e, __runWithRuntime as f, __setRuntime as g, AuthVerifier as h, type CreateAppOptions as i, type EngineConfig as j, RateLimiter as k, type RequestDatabase as l, type RouteEntry as m, type RuntimeHooks as n, type ScrubResult as o, type SqlDriver as p, type SqlTx as q, buildRouteTable as r, createApp as s, createLazyTransaction as t, createOps as u, createRequestDatabase as v, effectiveAuth as w, hostAllowed as x, installEgressFence as y, loadConfig as z };
+export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, createOps as G, createRequestDatabase as H, effectiveAuth as I, hostAllowed as J, installEgressFence as K, type LifecycleHook as L, type ModuleClients as M, Notifications as N, loadConfig as O, makeMemoryCache as P, matchRoute as Q, Realtime as R, Secrets as S, quoteIdent as T, scrubSecrets as U, withTables as V, __getRuntime as _, Documents as a, Log as b, type RequestStore as c, type RuntimeServices as d, type ShutdownRunner as e, Storage as f, __requestALS as g, __resetLifecycleHooks as h, __runStartHooks as i, __runWithRuntime as j, __setRuntime as k, onStart as l, AuthVerifier as m, type CreateAppOptions as n, onShutdown as o, type EngineConfig as p, RateLimiter as q, type RequestDatabase as r, type RouteEntry as s, type RuntimeHooks as t, type ScrubResult as u, type SqlDriver as v, type SqlTx as w, buildRouteTable as x, createApp as y, createLazyTransaction as z };