better-supabase 0.0.0 → 0.2.0

package/dist/testing/index.d.ts

@@ -0,0 +1,325 @@
+import { d as Generator, f as GeneratorInput, y as ResolvedConfig } from "../index-DOsjFvMf.js";
+import { A as SchemaMeta, N as TableKey, R as Update, _ as Insert, n as AnyModels, t as AnyFunctions } from "../types-C83v5SQz.js";
+import { r as Executor } from "../executor-CGdNQ27g.js";
+import { P as DbStats, l as CacheAdapter, t as BetterSupabase, y as Db } from "../define-e3zI4_4g.js";
+import { h as RequestContext, n as AnyPlugin } from "../plugin-C4TR9J0Z.js";
+import { t as SqlClient } from "../executor-BYXQ9AGn.js";
+import { t as Postgres } from "../pool-R2m_DkXi.js";
+import { n as AuthResolver } from "../resolve-CjHILk2w.js";
+import { r as EventSink, t as CloudEvent } from "../index-Ciu5Xlml.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/testing/jwt.d.ts
+interface TestJwtClaims {
+  readonly sub: string;
+  readonly role?: string;
+  readonly email?: string;
+  readonly aal?: "aal1" | "aal2";
+  readonly expiresIn?: number;
+  readonly [claim: string]: unknown;
+}
+/**
+ * Signs an HS256 access token the local Supabase stack accepts. Test-only:
+ * production tokens come from Supabase Auth.
+ */
+export declare function signTestJwt(secret: string, claims: TestJwtClaims): Promise<string>;
+/**
+ * Accepts `signTestJwt` tokens as users, for API servers tested against the
+ * local stack: `createServer(sb, { auth: { resolvers: [localAuth(secret)] } })`.
+ * Tokens that are not HS256-signed with `secret` fall through. Test-only.
+ */
+export declare function localAuth(secret: string): AuthResolver;
+interface TestSigner {
+  /** Public JWKS; pass as `jwks` to `resolveAuth` / `createServer({ auth: { jwks } })`. */
+  readonly jwks: {
+    readonly keys: readonly JsonWebKey[];
+  };
+  sign(claims: TestJwtClaims): Promise<string>;
+}
+/** A private ES256 JWK, as `better-supabase keys` writes to `supabase/signing_keys.json`. */
+interface SigningJwk extends JsonWebKey {
+  readonly kid: string;
+}
+/**
+ * Signs an ES256 access token with a private JWK, the way the local stack
+ * signs them once `signing_keys_path` is set. Test-only.
+ */
+export declare function signTestJwtWithKey(key: SigningJwk, claims: TestJwtClaims): Promise<string>;
+/** An in-memory ES256 key pair that signs tokens like Supabase Auth's asymmetric keys. */
+export declare function createTestSigner(): Promise<TestSigner>;
+//#endregion
+//#region src/testing/local-key.d.ts
+/**
+ * The key the local stack signs with: the first entry of the file
+ * `better-supabase keys` wrote. `path` defaults to `$SUPABASE_SIGNING_KEYS_PATH`,
+ * then `signing_keys_path` from the nearest `supabase/config.toml`.
+ */
+export declare function localSigningKey(path?: string): Promise<SigningJwk>;
+/** Signs a token with the local stack's ES256 key (see `localSigningKey`). Test-only. */
+export declare function signLocalJwt(claims: TestJwtClaims, path?: string): Promise<string>;
+//#endregion
+//#region src/testing/as-user.d.ts
+/** The local CLI stack's default JWT secret. */
+export declare const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long";
+interface LocalStack {
+  /** Defaults to `$SUPABASE_URL`, then `http://127.0.0.1:54321`. */
+  readonly url?: string;
+  /** Defaults to `$SUPABASE_PUBLISHABLE_KEY`, then `$SUPABASE_ANON_KEY`. */
+  readonly publishableKey?: string;
+  /**
+   * `ES256` (default) signs with the key `better-supabase keys` wrote, as
+   * the hosted project's asymmetric keys do. `HS256` signs with the shared
+   * JWT secret and only works against a local stack.
+   */
+  readonly alg?: "ES256" | "HS256";
+  /** The private ES256 key. Defaults to the first key in `signingKeysPath`. */
+  readonly signingKey?: SigningJwk;
+  /** Defaults to `$SUPABASE_SIGNING_KEYS_PATH`, then `signing_keys_path` in `supabase/config.toml`. */
+  readonly signingKeysPath?: string;
+  /** For `alg: 'HS256'`. Defaults to `$SUPABASE_JWT_SECRET`, then the CLI default. */
+  readonly jwtSecret?: string;
+  /** Service-role key for `expectTenantIsolation`; defaults to `$SUPABASE_SECRET_KEY`. */
+  readonly secretKey?: string;
+  /** Enables `sql`: the same user over direct Postgres. */
+  readonly postgres?: Postgres;
+}
+interface TestUser<M extends AnyModels, F extends AnyFunctions, E> {
+  readonly token: string;
+  readonly claims: TestJwtClaims;
+  /** supabase-js signed in as the user (storage, realtime, functions). */
+  readonly supabase: SupabaseClient;
+  /** Repositories over PostgREST as the user; RLS applies. */
+  readonly db: Db<M, F, E, SupabaseClient>;
+  /** Repositories over direct Postgres as the user, when `postgres` is given. */
+  readonly sql: Db<M, F, E, unknown> | undefined;
+}
+/**
+ * A test user against the local stack: a signed token and repositories that
+ * run as that user, for live RLS tests. The token is ES256-signed with the
+ * key from `better-supabase keys`; pass `{ alg: 'HS256' }` for a stack that
+ * still uses the shared JWT secret.
+ *
+ * ```ts
+ * const alice = await asUser(sb, { sub: aliceId, tenant_id: acme });
+ * expect(await alice.db.customers.count().orThrow()).toBe(3);
+ * ```
+ */
+export declare function asUser<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, claims: TestJwtClaims, stack?: LocalStack): Promise<TestUser<M, F, E>>;
+//#endregion
+//#region src/testing/budget.d.ts
+/** The part of a Playwright `Response` the budget check reads. */
+interface BudgetResponse {
+  url(): string;
+  headers(): Record<string, string>;
+  finished(): Promise<unknown>;
+  request(): {
+    headers(): Record<string, string>;
+  };
+}
+/** The part of a Playwright `Page` the budget check uses. */
+interface BudgetPage {
+  on(event: "response", listener: (response: BudgetResponse) => void): unknown;
+  off(event: "response", listener: (response: BudgetResponse) => void): unknown;
+  reload(): Promise<unknown>;
+  readonly request: {
+    get(url: string): Promise<{
+      ok(): boolean;
+      status(): number;
+      json(): Promise<unknown>;
+    }>;
+  };
+}
+interface DbBudgetExpectation {
+  readonly maxCalls?: number;
+  readonly maxWaves?: number;
+  /** The navigation to measure. Defaults to reloading the page. */
+  readonly during?: () => Promise<unknown>;
+  /** Also measure router prefetches. Defaults to false. */
+  readonly prefetches?: boolean;
+  /** How long to wait for a streamed response to finish. Defaults to 10 seconds. */
+  readonly timeoutMs?: number;
+}
+interface MeasuredRender {
+  readonly url: string;
+  readonly requestId: string;
+  readonly stats: DbStats;
+}
+/**
+ * Measures every document and RSC navigation response during `during` and
+ * fails when one render makes more database calls or waves than allowed.
+ * Needs `createNext(sb, { debug })` and `next.debugRoute()` in the app.
+ */
+export declare function expectDbBudget(page: BudgetPage, expectation: DbBudgetExpectation): Promise<readonly MeasuredRender[]>;
+//#endregion
+//#region src/testing/conformance.d.ts
+interface ConformanceCheck {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly message?: string;
+}
+interface ConformanceReport {
+  /** `Executor "postgrest"`, `CacheAdapter "next"`, ... */
+  readonly subject: string;
+  readonly checks: readonly ConformanceCheck[];
+}
+/** Thrown by a conformance kit when any check fails. Lists every failure, not just the first. */
+export declare class ConformanceError extends Error {
+  readonly report: ConformanceReport;
+  constructor(report: ConformanceReport);
+}
+type AnySupabase = BetterSupabase<any, any, any, any>;
+interface TestExecutorOptions {
+  /** A definition whose schema matches the executor's database. Install no plugins. */
+  readonly sb: AnySupabase;
+  /** App key of a table with rows the executor can read. Defaults to the first table. */
+  readonly table?: string;
+  /** A row to insert and delete again, to check writes. Skips write checks when omitted. */
+  readonly create?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Proves an `Executor` meets the contract: rows keyed by the selection's
+ * aliases, counts, `aborted` errors, failures returned as `Result`s rather
+ * than thrown, and (with `create`) a write round trip.
+ *
+ * ```ts
+ * it('conforms', () => testExecutor(myExecutor, { sb, table: 'tags', create: { name: 'x' } }));
+ * ```
+ */
+export declare function testExecutor(executor: Executor, options: TestExecutorOptions): Promise<ConformanceReport>;
+/**
+ * Proves a `CacheAdapter` accepts table and row targets, repeated and
+ * concurrent calls, and never mutates its input.
+ */
+export declare function testCacheAdapter(adapter: CacheAdapter, options?: {
+  readonly table?: string;
+}): Promise<ConformanceReport>;
+interface TestEventSinkOptions {
+  /** Events the sink delivered, for sinks that can be read back (an outbox, a test queue). */
+  readonly received?: () => readonly CloudEvent[] | Promise<readonly CloudEvent[]>;
+}
+/** Proves an `EventSink` accepts empty and full batches without mutating them, and delivers them when readable. */
+export declare function testEventSink(sink: EventSink, options?: TestEventSinkOptions): Promise<ConformanceReport>;
+interface TestAuthResolverOptions {
+  /** Requests with credentials this resolver owns but that must not verify. */
+  readonly invalid: readonly Request[];
+  /** Requests that must resolve to a user or service, optionally with the expected user id. */
+  readonly valid?: readonly {
+    readonly request: Request;
+    readonly userId?: string;
+  }[];
+  /** A request without this resolver's credentials. Defaults to a bare GET. */
+  readonly unrelated?: Request;
+}
+/**
+ * Proves an `AuthResolver` passes on requests it doesn't understand, fails
+ * closed (`invalid`, never anon) on bad credentials, and never throws.
+ */
+export declare function testAuthResolver(resolver: AuthResolver, options: TestAuthResolverOptions): Promise<ConformanceReport>;
+interface TestGeneratorOptions {
+  /** Schema metadata to generate from: `schema.meta` from your generated module. */
+  readonly meta: SchemaMeta;
+  /** Typegen metadata; defaults to an empty database. */
+  readonly introspection?: GeneratorInput["introspection"];
+  readonly extras?: GeneratorInput["extras"];
+  readonly config?: ResolvedConfig;
+}
+/** Proves a `Generator` writes relative, unique paths, is deterministic and doesn't mutate its input. */
+export declare function testGenerator(generator: Generator, options: TestGeneratorOptions): Promise<ConformanceReport>;
+interface TestPluginOptions {
+  /** The definition without this plugin. */
+  readonly sb: AnySupabase;
+  /** Table to exercise. Defaults to the first table. */
+  readonly table?: string;
+  /** Context the plugin needs, such as `{ tenant }` for `tenant()`. */
+  readonly context?: RequestContext;
+  /** Row for `create`, to exercise `beforeMutation`. */
+  readonly create?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Proves a `Plugin` targets API v1, installs cleanly, keeps `transformQuery`
+ * and `beforeMutation` pure and deterministic, and keeps executors'
+ * results intact when it wraps them.
+ */
+export declare function testPlugin(plugin: AnyPlugin, options: TestPluginOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/isolation.d.ts
+interface IsolationTenant {
+  /** Handed to each table's `row`, usually the tenant's id. */
+  readonly id: string;
+  /** The claims of a user in this tenant, as for `asUser`. */
+  readonly claims: TestJwtClaims;
+  /** Used in failure messages; defaults to `id`. */
+  readonly name?: string;
+}
+interface IsolationTable<M extends AnyModels, K extends keyof M> {
+  /**
+   * A row owned by `tenant`. `n` is 0 for the row seeded through the service
+   * role and 1 for the other tenant's insert attempt: put it in unique columns.
+   */
+  readonly row: (tenant: IsolationTenant, n: 0 | 1) => Insert<M, K>;
+  /** A change the other tenant tries to make. It must differ from `row`. */
+  readonly update: Update<M, K>;
+}
+type IsolationTables<M extends AnyModels> = { readonly [K in TableKey<M>]?: IsolationTable<M, K>; };
+interface TenantIsolationOptions<M extends AnyModels> {
+  readonly tenants: readonly [IsolationTenant, IsolationTenant];
+  readonly tables: IsolationTables<M>;
+  /** Defaults to `$SUPABASE_URL`, `$SUPABASE_PUBLISHABLE_KEY` and `$SUPABASE_SECRET_KEY`. */
+  readonly stack?: LocalStack;
+  /** Runs before any row is created, e.g. `() => seed.insert(sql)` for the tenants and their memberships. */
+  readonly seed?: () => Promise<void>;
+}
+/**
+ * Checks row-level security between two tenants against a running stack: for
+ * each table, a user of one tenant must not select, insert, update or delete
+ * the other tenant's rows. Runs without `sb`'s plugins, so the `tenant()`
+ * plugin can't hide a missing policy. Throws a `ConformanceError` naming each
+ * table and command that leaks; removes every row it created.
+ *
+ * ```ts
+ * await expectTenantIsolation(sb, {
+ *   tenants: [
+ *     { id: ACME, claims: { sub: alice, tenant_id: ACME } },
+ *     { id: GLOBEX, claims: { sub: bob, tenant_id: GLOBEX } },
+ *   ],
+ *   tables: {
+ *     tags: {
+ *       row: (tenant, n) => ({ organizationId: tenant.id, name: `iso-${n}` }),
+ *       update: { name: 'changed' },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function expectTenantIsolation<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options: TenantIsolationOptions<M>): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/seed.d.ts
+/** Named rows per table, in app casing: `{ customers: { acme: { ... } } }`. */
+type SeedFixtures<M extends AnyModels> = { readonly [K in keyof M]?: Readonly<Record<string, M[K]["Insert"]>>; };
+/** Rejects columns that are not in the table's Insert type. */
+type ExactSeed<M extends AnyModels, S> = { readonly [K in keyof S]: K extends keyof M ? { readonly [N in keyof S[K]]: { readonly [C in keyof S[K][N]]: C extends keyof M[K]["Insert"] ? S[K][N][C] : never; }; } : never; };
+declare const SEED: unique symbol;
+interface Seed<S> {
+  readonly [SEED]: true;
+  /** The fixtures as given, so tests can reference `seed.rows.customers.acme.id`. */
+  readonly rows: S;
+  /** One `insert ... on conflict do nothing` per table, parents before children. */
+  statements(): string[];
+  sql(): string;
+  /** Inserts the fixtures, e.g. in a test's `beforeAll`. Needs a service-role client. */
+  insert(sql: SqlClient): Promise<void>;
+}
+export declare function isSeed(value: unknown): value is Seed<unknown>;
+/**
+ * Typed fixtures shared by `supabase/seeds` and your tests. Rows use app
+ * casing and Insert types; `better-supabase seed` renders them to SQL.
+ *
+ * ```ts
+ * export const seed = defineSeed(sb, {
+ *   organizations: { acme: { id: ACME, name: 'Acme' } },
+ *   customers: { first: { organizationId: ACME, name: 'First customer' } },
+ * });
+ * ```
+ */
+export declare function defineSeed<M extends AnyModels, D, F extends AnyFunctions, E, const S extends SeedFixtures<M>>(sb: BetterSupabase<M, D, F, E>, fixtures: S & ExactSeed<M, S>): Seed<S>;
+//#endregion
+export type { BudgetPage, BudgetResponse, ConformanceCheck, ConformanceReport, DbBudgetExpectation, ExactSeed, IsolationTable, IsolationTables, IsolationTenant, LocalStack, MeasuredRender, Seed, SeedFixtures, SigningJwk, TenantIsolationOptions, TestAuthResolverOptions, TestEventSinkOptions, TestExecutorOptions, TestGeneratorOptions, TestJwtClaims, TestPluginOptions, TestSigner, TestUser };