@adrdp/pg-rest 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import { n as DbSession, r as Row, t as DbAdapter } from "./adapter-SqPs6SuJ.js";
+
+//#region src/parse/request.d.ts
+type Method = "GET" | "HEAD" | "POST" | "PATCH" | "PUT" | "DELETE" | "OPTIONS";
+//#endregion
+//#region src/schema.d.ts
+interface Column {
+  readonly name: string;
+  /** Result of `format_type`, e.g. `integer`, `character varying(10)`, `text[]`. */
+  readonly type: string;
+  readonly nullable: boolean;
+  readonly hasDefault: boolean;
+  /** SQL text of the default expression, when there is one. */
+  readonly defaultExpr: string | null;
+  readonly generated: boolean;
+  readonly comment: string | null;
+  readonly position: number;
+}
+type RelationKind = "table" | "view" | "matview" | "foreign" | "partitioned";
+interface Relation {
+  readonly schema: string;
+  readonly name: string;
+  readonly kind: RelationKind;
+  readonly columns: ReadonlyArray<Column>;
+  readonly pk: ReadonlyArray<string>;
+  readonly uniques: ReadonlyArray<ReadonlyArray<string>>;
+  readonly insertable: boolean;
+  readonly updatable: boolean;
+  readonly deletable: boolean;
+  readonly comment: string | null;
+}
+interface ForeignKey {
+  readonly name: string;
+  readonly schema: string;
+  readonly table: string;
+  readonly cols: ReadonlyArray<string>;
+  readonly fschema: string;
+  readonly ftable: string;
+  readonly fcols: ReadonlyArray<string>;
+}
+interface FunctionArg {
+  readonly name: string;
+  readonly type: string;
+  readonly hasDefault: boolean;
+  readonly variadic: boolean;
+}
+interface FunctionDef {
+  readonly schema: string;
+  readonly name: string;
+  readonly args: ReadonlyArray<FunctionArg>;
+  readonly returnType: string;
+  readonly returnsSet: boolean;
+  /** True if the function returns a composite / record / TABLE(...) row type. */
+  readonly returnsComposite: boolean;
+  readonly returnsVoid: boolean;
+  readonly volatility: "immutable" | "stable" | "volatile";
+  readonly comment: string | null;
+  /** The table when the function's only parameter is a table row (computed relationships). */
+  readonly argRelation?: {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** The table whose rows the function returns. */
+  readonly returnRelation?: {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** Planner row estimate; 1 on a set-returning function makes a computed relationship to-one. */
+  readonly rows: number;
+  /** Scalar functions returning a domain named like a media type (`"text/plain"`, …): the raw value is the body. */
+  readonly returnMediaType?: {
+    readonly name: string;
+    readonly bytea: boolean;
+  };
+}
+/** A custom media type handler: an aggregate named after the media type that returns a domain (see PostgREST's "custom media types"). */
+interface MediaHandler {
+  readonly schema: string;
+  /** The aggregate's name, i.e. the media type (for example `text/plain`, or the catch-all). */
+  readonly mediaType: string;
+  /** The table whose rows it aggregates, or `undefined` for `anyelement`. */
+  readonly argRelation?: {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** True when the domain wraps `bytea` (the body is binary). */
+  readonly bytea: boolean;
+}
+interface SchemaCache {
+  readonly mediaHandlers: ReadonlyArray<MediaHandler>;
+  readonly schemas: ReadonlyArray<string>;
+  readonly relations: ReadonlyMap<string, Relation>;
+  readonly foreignKeys: ReadonlyArray<ForeignKey>;
+  readonly functions: ReadonlyMap<string, ReadonlyArray<FunctionDef>>;
+}
+//#endregion
+//#region src/core.d.ts
+/** Who is making the request, as far as the database is concerned. */
+interface RequestContext {
+  /** Database role to run the request as. Defaults to the anonymous role. */
+  readonly role?: string | undefined;
+  /**
+   * Claims exposed to SQL as `current_setting('request.jwt.claims')`.
+   * This is what RLS policies read, e.g. `{ sub: "user-123" }`.
+   * No signature is involved: you decide who the user is.
+   */
+  readonly claims?: Readonly<Record<string, unknown>> | undefined;
+  /** Extra settings, set with `set_config(name, value, true)`. Names need a dot: `app.tenant_id`. */
+  readonly settings?: Readonly<Record<string, string>> | undefined;
+}
+interface PreRequestInfo {
+  readonly role: string;
+  readonly claims: Readonly<Record<string, unknown>>;
+  readonly method: Method;
+  readonly path: string;
+  readonly request: Request;
+}
+interface CoreConfig {
+  readonly schemas: ReadonlyArray<string>;
+  /** Role for requests without one; `undefined` refuses anonymous access (PGRST302). */
+  readonly anonymousRole: string | undefined;
+  readonly maxRows?: number | undefined;
+  readonly basePath: string;
+  readonly extraSearchPath: ReadonlyArray<string>;
+  /** Honor `Prefer: tx=rollback|commit` (PostgREST `db-tx-end`). */
+  readonly allowTxOverride: boolean;
+  /** Answer `Accept: application/vnd.pgrst.plan` with the query plan. */
+  readonly planEnabled: boolean;
+  readonly openApi: boolean;
+  /** Expose `request.headers` / `request.cookies` / `request.method` / `request.path` to SQL. */
+  readonly requestSettings: boolean;
+  /** SQL function (`"auth"."check"`) or callback run in the transaction before the request (db-pre-request). */
+  readonly preRequest?: string | ((session: DbSession, info: PreRequestInfo) => Promise<void>) | undefined;
+  readonly serverUrl?: string | undefined;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error body, in the exact shape PostgREST returns:
+ * `{ code, message, details, hint }`.
+ */
+interface ErrorBody {
+  readonly code: string;
+  readonly message: string;
+  readonly details: string | null;
+  readonly hint: string | null;
+}
+/**
+ * Thrown by the pure parts of the library (parsers, SQL builders). It is
+ * converted into an {@link ApiError} at the request boundary.
+ */
+declare class PgRestError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly details: string | null;
+  readonly hint: string | null;
+  readonly headers: Readonly<Record<string, string>>;
+  constructor(status: number, code: string, message: string, details?: string | null, hint?: string | null, headers?: Readonly<Record<string, string>>);
+  get body(): ErrorBody;
+}
+/** An error that has already been mapped to an HTTP response. */
+declare class ApiError extends Error {
+  readonly _tag = "ApiError";
+  readonly status: number;
+  readonly body: ErrorBody;
+  readonly headers: Readonly<Record<string, string>>;
+  constructor(fields: {
+    readonly status: number;
+    readonly body: ErrorBody;
+    readonly headers: Readonly<Record<string, string>>;
+  });
+}
+/** Failure talking to the database, carrying Postgres error fields. */
+interface DbErrorInfo {
+  /** SQLSTATE, e.g. "23505", or a custom code such as "PT401" / "PGRST". */
+  readonly sqlState: string;
+  readonly message: string;
+  readonly detail?: string | undefined;
+  readonly hint?: string | undefined;
+}
+/** Normalized error thrown by a {@link DbAdapter}. */
+declare class DbQueryError extends Error implements DbErrorInfo {
+  readonly sqlState: string;
+  readonly detail?: string | undefined;
+  readonly hint?: string | undefined;
+  constructor(sqlState: string, message: string, detail?: string | undefined, hint?: string | undefined);
+}
+//#endregion
+//#region src/service.d.ts
+/** The schema could not be read from the database catalog. */
+declare class SchemaLoadError extends Error {
+  readonly cause: unknown;
+  readonly _tag = "SchemaLoadError";
+  constructor(cause: unknown);
+}
+//#endregion
+//#region src/index.d.ts
+interface PgRestOptions {
+  /**
+   * The database, as a {@link DbAdapter} you create from your driver
+   * (Bun.sql, node-postgres, postgres.js, PGlite...). See `example/adapters`.
+   * pg-rest never closes it: you own its lifecycle.
+   */
+  readonly db: DbAdapter;
+  /** Schemas to expose. The first one is the default. Default `["public"]`. */
+  readonly schemas?: ReadonlyArray<string>;
+  /**
+   * Role used when the request context has none. Default `"anon"`. `false` refuses anonymous requests
+   * with `401 PGRST302` (like PostgREST without `db-anon-role`).
+   */
+  readonly anonymousRole?: string | false;
+  /**
+   * Decide who is calling. Return the role and claims (what RLS policies read
+   * from `request.jwt.claims`). There is no JWT: use a session cookie, an API
+   * key, your auth library... Throw a {@link PgRestError} to reject the request
+   * (e.g. `new PgRestError(401, "unauthorized", "Please sign in")`).
+   *
+   * Used by `handle(request)` when no explicit context is passed.
+   */
+  readonly resolveContext?: (request: Request) => RequestContext | undefined | Promise<RequestContext | undefined>;
+  /** Maximum rows returned by a read (PostgREST `db-max-rows`). */
+  readonly maxRows?: number;
+  /** Mount path to strip from request URLs, e.g. `/api`. */
+  readonly basePath?: string;
+  /** Appended to `search_path` after the selected schema. Default `["public"]`. */
+  readonly extraSearchPath?: ReadonlyArray<string>;
+  /** Honor `Prefer: tx=rollback` (PostgREST `db-tx-end`). Default `false`. */
+  readonly allowTxOverride?: boolean;
+  /**
+   * Answer `Accept: application/vnd.pgrst.plan` requests with the query plan (PostgREST `db-plan-enabled`).
+   * A plan reveals the structure of the database: keep it off, or restrict it, in production. Default `false`.
+   */
+  readonly planEnabled?: boolean;
+  /** Serve the OpenAPI document at `/`. Default `true`. */
+  readonly openApi?: boolean;
+  /** Expose `request.headers`, `request.cookies`, `request.method`, `request.path` to SQL. Default `true`. */
+  readonly requestSettings?: boolean;
+  /** A SQL function (`"auth.check_request"`) or callback to run before each request (PostgREST `db-pre-request`). */
+  readonly preRequest?: CoreConfig["preRequest"];
+  /** Public URL, used as `host` in the OpenAPI document. Defaults to the request origin. */
+  readonly serverUrl?: string;
+}
+interface PgRestInstance {
+  /**
+   * Handle a request. Pass `ctx` to set the user explicitly; otherwise
+   * `resolveContext` is used; otherwise the request runs as the anonymous role.
+   */
+  handle(request: Request, ctx?: RequestContext): Promise<Response>;
+  /** Re-read the database catalog (after migrations). */
+  reloadSchema(): Promise<void>;
+  /** The current introspected schema. */
+  schemaCache(): Promise<SchemaCache>;
+  /** Stop the handler. The database adapter is left open: close it yourself. */
+  close(): Promise<void>;
+}
+/** Create a PostgREST-compatible handler over a Postgres database. */
+declare const createPgRest: (options: PgRestOptions) => Promise<PgRestInstance>;
+//#endregion
+export { ApiError, type Column, type DbAdapter, DbQueryError, type DbSession, type ErrorBody, type ForeignKey, type FunctionDef, PgRestError, PgRestInstance, PgRestOptions, type PreRequestInfo, type Relation, type RequestContext, type Row, type SchemaCache, SchemaLoadError, createPgRest };