pocketbase-zod-schema 0.7.2 → 1.0.0

package/dist/verify-BF72n2df.d.ts

@@ -0,0 +1,402 @@
+import { R as RecordModel, m as EngineWarning, E as EngineOptions, C as CollectionStore, o as MigrationPlan, s as ReplayResult, q as PlanOptions, n as MigrationExecutionResult, u as RawCollection, M as MigrationDirection } from './types-B_MLb1Ob.js';
+
+/**
+ * Condition expressions — one evaluator for PocketBase filters and SQL WHERE
+ *
+ * Data migrations select records two ways: PocketBase's filter syntax
+ * (`status = "draft" && views > 10`) and raw SQL through `$dbx`/`app.db()`
+ * (`WHERE status = {:status}`). The two dialects overlap almost completely —
+ * the same comparison operators over the same field/literal operands — so the
+ * simulation parses both with one grammar and evaluates the result against a
+ * record.
+ *
+ * Deliberately small: comparisons, `LIKE`/`~`, `IN`, `IS NULL`, `AND`/`OR`/
+ * `NOT`, parentheses, and `{:name}` bindings. Anything outside that raises
+ * `ExpressionError`, which the caller reports as an unsupported query rather
+ * than silently matching the wrong rows.
+ */
+declare class ExpressionError extends Error {
+    constructor(message: string);
+}
+/** Resolves a field reference to the value stored on the row being tested */
+interface EvaluationContext {
+    field: (name: string) => unknown;
+    params?: Record<string, unknown>;
+}
+type Condition = {
+    kind: "and";
+    operands: Condition[];
+} | {
+    kind: "or";
+    operands: Condition[];
+} | {
+    kind: "not";
+    operand: Condition;
+} | {
+    kind: "compare";
+    operator: CompareOperator;
+    left: Operand;
+    right: Operand;
+} | {
+    kind: "in";
+    negated: boolean;
+    left: Operand;
+    values: Operand[];
+} | {
+    kind: "like";
+    negated: boolean;
+    left: Operand;
+    pattern: Operand;
+    implicitWildcards: boolean;
+} | {
+    kind: "null";
+    negated: boolean;
+    operand: Operand;
+} | {
+    kind: "between";
+    negated: boolean;
+    operand: Operand;
+    from: Operand;
+    to: Operand;
+} | {
+    kind: "literal";
+    value: boolean;
+};
+type CompareOperator = "=" | "!=" | ">" | ">=" | "<" | "<=";
+type Operand = {
+    kind: "field";
+    name: string;
+} | {
+    kind: "value";
+    value: unknown;
+} | {
+    kind: "param";
+    name: string;
+};
+/** Parses a filter or SQL condition into an evaluable tree */
+declare function parseCondition(source: string): Condition;
+declare function evaluateCondition(condition: Condition, context: EvaluationContext): boolean;
+
+/**
+ * `$dbx` and `app.db()` simulation
+ *
+ * PocketBase exposes two query surfaces to a migration: `$dbx` expression
+ * builders passed to the record finders, and `app.db().newQuery(sql)` for raw
+ * SQL. Both are simulated against the in-memory record store (`records.ts`).
+ *
+ * The SQL support is a deliberate subset — SELECT / INSERT / UPDATE / DELETE
+ * against a single collection table, with the condition grammar from
+ * `expression.ts`. Anything beyond it raises `UnsupportedQueryError`, which
+ * the caller turns into a warning (lenient) or a throw (strict): reporting
+ * "this query is not simulated" is useful, quietly matching the wrong rows is
+ * not.
+ */
+
+declare class UnsupportedQueryError extends Error {
+    constructor(message: string);
+}
+/** Marks the objects `$dbx.*` returns so the finders can recognize them */
+declare const DBX_EXPRESSION: unique symbol;
+interface DbxExpression {
+    [DBX_EXPRESSION]: true;
+    /** The SQL fragment, as `$dbx` would build it (for messages and debugging) */
+    build(): string;
+    matches(record: RecordModel): boolean;
+}
+declare function isDbxExpression(value: unknown): value is DbxExpression;
+declare function createDbx(): Record<string, unknown>;
+type ParsedStatement = {
+    kind: "select";
+    table: string;
+    columns: string[];
+    where?: Condition;
+    order?: OrderTerm[];
+    limit?: number;
+    offset?: number;
+} | {
+    kind: "update";
+    table: string;
+    assignments: {
+        column: string;
+        value: Operand;
+    }[];
+    where?: Condition;
+} | {
+    kind: "delete";
+    table: string;
+    where?: Condition;
+} | {
+    kind: "insert";
+    table: string;
+    columns: string[];
+    values: Operand[];
+};
+interface OrderTerm {
+    column: string;
+    descending: boolean;
+}
+/**
+ * Parses one statement of the supported subset.
+ *
+ * @throws UnsupportedQueryError for anything outside it
+ */
+declare function parseStatement(sql: string): ParsedStatement;
+
+/**
+ * goja-compatibility lint
+ *
+ * The engine executes migrations with Node's JavaScript, a superset of the
+ * goja dialect PocketBase actually runs. That gap is silent: a migration can
+ * replay perfectly here, pass verification, and still fail the moment
+ * `pocketbase migrate up` reaches it — because it referenced a Node global,
+ * used class fields, or awaited a promise in a runtime with no event loop.
+ *
+ * This pass closes the gap statically. It parses the file with acorn and
+ * reports:
+ *
+ * - `unknown-global` — a free identifier that is neither declared in the file
+ *   nor part of the PocketBase JSVM surface (the sandbox globals) or the
+ *   ECMAScript library goja implements. `require`, `process`, `Buffer`,
+ *   `fetch`, `setTimeout` all land here.
+ * - `unsupported-syntax` — constructs goja's parser rejects: class fields,
+ *   private members, static blocks, BigInt literals, `import.meta`.
+ * - `module-syntax` — `import`/`export`; migrations are scripts.
+ * - `async` — `async`/`await`/`Promise`. goja runs migrations synchronously,
+ *   so an awaited promise never settles.
+ * - `unsupported-api` — folded in from execution warnings: a call that
+ *   resolved to an inert stub did nothing here and will do something (or
+ *   throw) in production.
+ */
+
+type GojaLintRule = "syntax" | "unsupported-syntax" | "module-syntax" | "async" | "unknown-global" | "unsupported-api";
+type GojaLintSeverity = "error" | "warning";
+interface GojaLintFinding {
+    rule: GojaLintRule;
+    severity: GojaLintSeverity;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+}
+interface GojaLintResult {
+    file: string;
+    findings: GojaLintFinding[];
+    /** No error-severity findings */
+    ok: boolean;
+}
+interface GojaLintOptions {
+    /** Path or name used in messages */
+    file?: string;
+    /**
+     * Extra globals to treat as available — for a PocketBase build that
+     * registers its own JSVM bindings.
+     */
+    allowedGlobals?: string[];
+    /**
+     * Engine warnings from executing the same file. `unsupported-api` entries
+     * become findings, which is how a stubbed call gets surfaced prominently
+     * instead of being buried in replay output.
+     */
+    warnings?: EngineWarning[];
+}
+/** The identifiers a migration may reference without declaring them */
+declare function availableGlobals(extra?: string[]): Set<string>;
+declare function lintMigrationSource(source: string, options?: GojaLintOptions): GojaLintResult;
+declare function lintMigrationFile(filePath: string, options?: GojaLintOptions): GojaLintResult;
+declare function lintMigrationFiles(files: string[], options?: GojaLintOptions): GojaLintResult[];
+/** Turns engine execution warnings into findings */
+declare function gojaFindingsFromWarnings(warnings?: EngineWarning[]): GojaLintFinding[];
+declare function formatGojaLintFinding(finding: GojaLintFinding): string;
+
+/**
+ * Replayer — folds an ordered list of migration files into a final state
+ *
+ * Mirrors what PocketBase does on `migrate up`: execute each unapplied file
+ * in timestamp order. State reconstruction starts from an empty store; a
+ * native snapshot migration (app.importCollections) is just the first file.
+ *
+ * Which files that is comes from `planMigrationReplay`: by default the newest
+ * snapshot plus everything after it, or — when an applied-migrations list is
+ * supplied — only the files PocketBase has actually run, starting from the
+ * newest applied snapshot.
+ */
+
+declare function replayMigrations(files: string[], options?: EngineOptions & {
+    initialStore?: CollectionStore;
+    plan?: MigrationPlan;
+}): ReplayResult;
+/**
+ * Replays a pb_migrations directory: the snapshot the state starts from,
+ * then every migration after it, in timestamp order.
+ *
+ * Pass `applied` (from `readAppliedMigrations`) to replay only what PocketBase
+ * has actually run — otherwise every file on disk is assumed applied.
+ *
+ * Returns null when there is nothing to replay (an empty database).
+ */
+declare function replayMigrationsDirectory(migrationsPath: string, options?: EngineOptions & PlanOptions): ReplayResult | null;
+
+/**
+ * Runner — executes one migration file against a CollectionStore
+ *
+ * Evaluation happens in a vm context built from the sandbox globals; the
+ * file's migrate(up, down) call registers its closures. The requested
+ * direction then runs transactionally: the store is cloned, the closure is
+ * applied to the clone, and the clone replaces the store only on success.
+ * The closure is invoked from inside the context (not host code) so the vm
+ * timeout also bounds infinite loops within migration bodies.
+ *
+ * State reconstruction only ever runs `up`, which structurally rules out
+ * replaying rollback statements as forward operations. `down` is executed on request (`executeMigrationDownSource`),
+ * for rollback verification — see `verify.ts`. Downs run in reverse
+ * registration order, mirroring how PocketBase rolls back.
+ */
+
+declare function executeMigrationSource(source: string, store: CollectionStore, options?: EngineOptions & {
+    filename?: string;
+}): MigrationExecutionResult;
+declare function executeMigrationFile(filePath: string, store: CollectionStore, options?: EngineOptions): MigrationExecutionResult;
+/**
+ * Runs the file's `down()` closures against the store, newest registration
+ * first. A file that registers no `down` leaves the store untouched and
+ * reports `applied: false`.
+ */
+declare function executeMigrationDownSource(source: string, store: CollectionStore, options?: EngineOptions & {
+    filename?: string;
+}): MigrationExecutionResult;
+declare function executeMigrationDownFile(filePath: string, store: CollectionStore, options?: EngineOptions): MigrationExecutionResult;
+
+/**
+ * Structural comparison of two engine states
+ *
+ * Down-migration verification asks one question — "is the state after
+ * up() + down() the state we started from?" — and needs an answer precise
+ * enough to name what drifted. This compares the raw PocketBase-shaped
+ * collections of two stores directly, rather than routing through the diff
+ * engine, because a rollback that leaves the schema semantically equal but
+ * structurally different (a restored field carrying a different id, an index
+ * re-added in a different form) is exactly the kind of drift verification
+ * exists to catch.
+ *
+ * Normalization is limited to differences PocketBase itself does not
+ * distinguish:
+ *
+ * - An option a migration never declared and one set to its Go zero value
+ *   (`""`, `0`, `false`, `[]`, `null`) express the same constraint, so an
+ *   absent key equals a zero-valued one. Two *declared* values are always
+ *   compared (`min: 0` vs `min: 5` is a real difference).
+ * - API rules are exempt from that rule: `null` (superuser only) and `""`
+ *   (public) are different permissions, so only absent ≡ `null` holds.
+ * - Index order is not meaningful; index lists are compared as sets.
+ * - Field order is not compared unless `strictFieldOrder` is set.
+ */
+
+interface StateDifference {
+    kind: "collection-added" | "collection-removed" | "collection-property" | "field-added" | "field-removed" | "field-property" | "field-order" | "indexes";
+    /** Collection name (baseline name when the collection exists on both sides) */
+    collection: string;
+    field?: string;
+    property?: string;
+    expected?: unknown;
+    actual?: unknown;
+    /** Human-readable one-liner, suitable for CLI output */
+    message: string;
+}
+interface StateCompareOptions {
+    /**
+     * Collection and field properties to skip.
+     * Defaults to PocketBase's own bookkeeping timestamps.
+     */
+    ignoreKeys?: string[];
+    /** Also compare the position of each field within its collection */
+    strictFieldOrder?: boolean;
+    /** Labels used in messages; defaults to "baseline" / "actual" */
+    labels?: {
+        expected: string;
+        actual: string;
+    };
+}
+/**
+ * Compares two stores. An empty result means the two states are the same
+ * schema; every entry names one concrete divergence.
+ */
+declare function compareStores(expected: CollectionStore, actual: CollectionStore, options?: StateCompareOptions): StateDifference[];
+declare function compareRawCollections(expected: RawCollection[], actual: RawCollection[], options?: StateCompareOptions): StateDifference[];
+/** One line per difference, e.g. for CLI output */
+declare function describeStateDifferences(differences: StateDifference[]): string[];
+
+/**
+ * Down-migration verification
+ *
+ * A generated `down()` is never exercised by state reconstruction — the
+ * replayer only runs `up()` — so a rollback that does not actually roll back
+ * stays invisible until someone runs `pocketbase migrate down` in anger.
+ * This module closes that gap: for each migration it executes `up()` against
+ * a baseline, then `down()` against the result, and asserts the state came
+ * back to the baseline.
+ *
+ * `down()` runs from a fresh evaluation of the file, the way PocketBase runs
+ * it — a separate invocation that cannot observe anything `up()` left in the
+ * file's module scope.
+ *
+ * Failures are returned, not thrown: a verification pass reports on every
+ * migration it was given, and the caller decides whether an unreversible
+ * migration is fatal.
+ */
+
+interface MigrationSourceRef {
+    source: string;
+    /** Path or name used in messages */
+    file?: string;
+}
+interface MigrationRoundTripResult {
+    file: string;
+    /** The file registered an up() closure and it committed */
+    upApplied: boolean;
+    /** The file registered a down() closure and it committed */
+    downApplied: boolean;
+    /** up() changed the state but the file has no down() to undo it */
+    missingDown: boolean;
+    /** up() followed by down() returned to the baseline */
+    reversible: boolean;
+    /** What the rollback failed to restore (empty when reversible) */
+    differences: StateDifference[];
+    warnings: EngineWarning[];
+    /** Set when a phase failed to execute at all */
+    error?: {
+        phase: MigrationDirection | "evaluate";
+        message: string;
+    };
+    /** State after up() — what the next migration in a sequence starts from */
+    storeAfterUp: CollectionStore;
+}
+interface MigrationVerificationReport {
+    results: MigrationRoundTripResult[];
+    /** Every migration executed and reversed cleanly */
+    ok: boolean;
+    /** State after every up() — the state the migrations leave behind */
+    store: CollectionStore;
+    /** Only the results that failed, in input order */
+    failures: MigrationRoundTripResult[];
+}
+interface VerifyOptions extends EngineOptions {
+    /** State the first migration is applied to. Defaults to an empty store. */
+    initialStore?: CollectionStore;
+    /** Forwarded to the state comparison */
+    compare?: StateCompareOptions;
+}
+/**
+ * Verifies one migration against a baseline. The baseline store is left
+ * untouched; the state after up() is returned on the result.
+ */
+declare function verifyMigrationRoundTrip(migration: MigrationSourceRef, baseline?: CollectionStore, options?: VerifyOptions): MigrationRoundTripResult;
+declare function verifyMigrationFileRoundTrip(filePath: string, baseline?: CollectionStore, options?: VerifyOptions): MigrationRoundTripResult;
+/**
+ * Verifies a sequence of migrations the way they will be applied: each one
+ * is round-tripped against the state its predecessors leave behind, and its
+ * up() is then committed before moving on.
+ */
+declare function verifyMigrationSources(migrations: MigrationSourceRef[], options?: VerifyOptions): MigrationVerificationReport;
+declare function verifyMigrationFiles(files: string[], options?: VerifyOptions): MigrationVerificationReport;
+
+export { type MigrationVerificationReport as A, type StateDifference as B, type Condition as C, type DbxExpression as D, ExpressionError as E, parseStatement as F, type GojaLintFinding as G, evaluateCondition as H, type EvaluationContext as I, compareRawCollections as J, type MigrationRoundTripResult as M, type StateCompareOptions as S, UnsupportedQueryError as U, type VerifyOptions as V, availableGlobals as a, createDbx as b, compareStores as c, describeStateDifferences as d, executeMigrationDownFile as e, executeMigrationDownSource as f, executeMigrationFile as g, executeMigrationSource as h, formatGojaLintFinding as i, gojaFindingsFromWarnings as j, isDbxExpression as k, lintMigrationFile as l, lintMigrationFiles as m, lintMigrationSource as n, replayMigrationsDirectory as o, parseCondition as p, verifyMigrationFiles as q, replayMigrations as r, verifyMigrationRoundTrip as s, verifyMigrationSources as t, type GojaLintOptions as u, verifyMigrationFileRoundTrip as v, type GojaLintResult as w, type GojaLintRule as x, type GojaLintSeverity as y, type MigrationSourceRef as z };