pocketbase-zod-schema 0.7.2 → 1.0.0

package/dist/types-upZBVMfb.d.cts

@@ -0,0 +1,475 @@
+import { a as SchemaSnapshot } from './types-CnzfX6JH.cjs';
+
+/**
+ * `_migrations` table awareness
+ *
+ * PocketBase records every migration it has run in an internal `_migrations`
+ * table (`file` TEXT PRIMARY KEY, `applied` INTEGER). Replay that assumes
+ * every file on disk is applied reconstructs a state the database may never
+ * have been in: a file added but not yet run, or a file deleted from disk
+ * after it ran, both produce silent drift.
+ *
+ * This module reads that table so replay can start from an actual checkpoint,
+ * and so `status --verify` can name the difference between disk and database.
+ *
+ * The read is done with Node's built-in `node:sqlite` (Node >= 22.5), fetched
+ * through `process.getBuiltinModule` so neither the ESM nor the CJS bundle
+ * carries a hard dependency on it. `pb_data/data.db` is opened **read-only**;
+ * a running PocketBase instance is never disturbed.
+ */
+/** PocketBase's internal table of applied migrations */
+declare const APPLIED_MIGRATIONS_TABLE = "_migrations";
+/** PocketBase's SQLite database file inside a pb_data directory */
+declare const POCKETBASE_DATABASE_FILENAME = "data.db";
+interface AppliedMigration {
+    /** Filename as PocketBase recorded it, e.g. "1712345678_created_Posts.js" */
+    file: string;
+    /** Unix seconds from `_migrations.applied`, when the column has a value */
+    applied?: number;
+}
+interface AppliedMigrationsSource {
+    /** Where the list came from — a database path, or a caller-supplied label */
+    origin: string;
+    /** Every row, in application order */
+    entries: AppliedMigration[];
+    /**
+     * Entries PocketBase's own Go core migrations contributed (`*.go`). They
+     * never correspond to a file in a pb_migrations directory, so they are
+     * kept separate from `entries` rather than reported as missing.
+     */
+    coreEntries: AppliedMigration[];
+}
+/**
+ * Raised when an applied-migrations list was requested but could not be read.
+ * Callers that treat the list as optional should catch this and fall back to
+ * "assume everything on disk is applied".
+ */
+declare class AppliedMigrationsError extends Error {
+    readonly source?: string;
+    readonly originalError?: Error;
+    constructor(message: string, source?: string, originalError?: Error);
+}
+/**
+ * Builds a source from an explicit list of filenames (paths are reduced to
+ * their basename, so a caller can pass either).
+ */
+declare function appliedMigrationsFromList(files: string[], origin?: string): AppliedMigrationsSource;
+/**
+ * The pb_data directory PocketBase uses alongside a pb_migrations directory.
+ * Both live under the PocketBase working directory, so pb_data is a sibling.
+ */
+declare function defaultDataDirectory(migrationsPath: string): string;
+/**
+ * Resolves a user-supplied pb_data path (directory or database file) to the
+ * SQLite file to open. Returns null when nothing usable exists.
+ */
+declare function resolveDatabasePath(dataPathOrFile: string): string | null;
+/**
+ * Reads `_migrations` out of a PocketBase SQLite database.
+ *
+ * @param dataPathOrFile - A pb_data directory or a data.db file
+ * @throws AppliedMigrationsError when the runtime, file, or table is unusable
+ */
+declare function readAppliedMigrations(dataPathOrFile: string): AppliedMigrationsSource;
+/**
+ * Best-effort read: returns null instead of throwing when there is simply no
+ * database to read (the common case for a checkout that has never run
+ * PocketBase). Genuine failures — an unreadable file, a missing table, a
+ * runtime without node:sqlite — still throw, because silently assuming
+ * "everything is applied" is the drift this module exists to catch.
+ */
+declare function readAppliedMigrationsIfPresent(dataPathOrFile: string): AppliedMigrationsSource | null;
+
+/**
+ * Replay planning — which migration files reconstruct the current state
+ *
+ * Without knowledge of PocketBase's `_migrations` table, replay assumes every
+ * file on disk has been applied. That is right for the common case and wrong
+ * in exactly the situations that matter: a migration written but not yet run,
+ * or a file removed from disk after it ran. Both produce a reconstructed state
+ * the database was never in, and therefore a wrong diff.
+ *
+ * Given an applied-migrations list (see `applied-migrations.ts`), this module
+ * turns a pb_migrations directory into a plan:
+ *
+ * - `filesToReplay` — the applied prefix, starting at the newest *applied*
+ *   snapshot, which is the checkpoint replay should start from
+ * - `pending` — on disk, never applied
+ * - `missing` — applied, no longer on disk
+ * - `outOfOrder` — pending files whose timestamp sits behind an already
+ *   applied one, so they will be applied out of authoring order
+ */
+
+/**
+ * Extracts the timestamp prefix from a migration filename.
+ * Migration files are named `[timestamp]_[description].js`.
+ *
+ * @param filename - Migration filename (basename, not a path)
+ * @returns Timestamp as a number, or null when the name is not prefixed
+ */
+declare function extractTimestampFromFilename(filename: string): number | null;
+/** A migration file discovered on disk */
+interface DiscoveredMigration {
+    /** Absolute path */
+    path: string;
+    /** Basename, which is what `_migrations.file` stores */
+    name: string;
+    timestamp: number;
+    /** PocketBase's own `*_collections_snapshot.js` files */
+    isSnapshot: boolean;
+}
+interface MigrationPlan {
+    /** The snapshot the replay starts from, when the directory has one */
+    snapshotFile: string | null;
+    /** Absolute paths to execute, in timestamp order */
+    filesToReplay: string[];
+    /** Basenames present on disk but absent from `_migrations` */
+    pending: string[];
+    /** Basenames recorded in `_migrations` with no file on disk */
+    missing: string[];
+    /**
+     * Basenames from `pending` whose timestamp precedes an already-applied
+     * migration. PocketBase will still run them, but after migrations authored
+     * later — so the state they produce depends on apply order.
+     */
+    outOfOrder: string[];
+    /** False when no applied list was supplied: every file is assumed applied */
+    appliedKnown: boolean;
+    /** Where the applied list came from, when there was one */
+    appliedOrigin?: string;
+    /** Number of JS migrations recorded as applied */
+    appliedCount: number;
+    /** True when disk and `_migrations` agree exactly */
+    inSync: boolean;
+}
+interface PlanOptions {
+    /**
+     * The applied-migrations list. A plain array of filenames is accepted as a
+     * shorthand. Omit (or pass null) to assume every file on disk is applied.
+     */
+    applied?: AppliedMigrationsSource | string[] | null;
+}
+/**
+ * Lists every timestamped `.js` migration in a directory, in timestamp order.
+ * Returns an empty list when the directory does not exist.
+ */
+declare function discoverMigrations(migrationsPath: string): DiscoveredMigration[];
+/**
+ * Builds the replay plan for a migrations directory.
+ *
+ * Without an applied list this reproduces the directory's default replay
+ * window — newest snapshot plus everything after it — so the plan is a
+ * drop-in for the previous file selection.
+ */
+declare function planMigrationReplay(migrationsPath: string, options?: PlanOptions): MigrationPlan;
+
+/**
+ * Runtime field constructors matching the PocketBase JSVM globals
+ *
+ * In the PocketBase JSVM, migrations construct fields via `new Field({...})`
+ * or typed constructors like `new TextField({...})`. Instances are plain
+ * mutable objects; migrations freely assign properties after construction
+ * (e.g. `field.max = 500`).
+ *
+ * The constructors deliberately add no default properties beyond `type`:
+ * the resulting state must match what the migration file literally declares,
+ * the same data the literal declares, materialized as a real object.
+ */
+/**
+ * Generic field constructor: `new Field({type: "number", ...})`.
+ * PocketBase's own generated migrations use this form with an explicit type.
+ */
+declare class Field {
+    [key: string]: any;
+    constructor(data?: Record<string, any>);
+}
+declare const TextField: new (data?: Record<string, any>) => Field;
+declare const EmailField: new (data?: Record<string, any>) => Field;
+declare const URLField: new (data?: Record<string, any>) => Field;
+declare const NumberField: new (data?: Record<string, any>) => Field;
+declare const BoolField: new (data?: Record<string, any>) => Field;
+declare const DateField: new (data?: Record<string, any>) => Field;
+declare const SelectField: new (data?: Record<string, any>) => Field;
+declare const RelationField: new (data?: Record<string, any>) => Field;
+declare const FileField: new (data?: Record<string, any>) => Field;
+declare const JSONField: new (data?: Record<string, any>) => Field;
+declare const EditorField: new (data?: Record<string, any>) => Field;
+declare const GeoPointField: new (data?: Record<string, any>) => Field;
+declare const AutodateField: new (data?: Record<string, any>) => Field;
+declare const PasswordField: new (data?: Record<string, any>) => Field;
+declare const FIELD_CONSTRUCTORS: Record<string, new (data?: Record<string, any>) => Field>;
+
+/**
+ * FieldsList — runtime equivalent of a PocketBase collection's `fields`
+ *
+ * Mirrors the methods the JSVM exposes on `collection.fields`:
+ * add / addAt / removeById / removeByName / getById / getByName, plus
+ * read-side iteration. Field entries are live objects — mutations through
+ * getByName() are visible when the collection is saved, exactly like the
+ * generator's `const f = collection.fields.getByName("x"); f.max = 500;`
+ * output expects.
+ */
+
+declare class FieldsList {
+    private items;
+    constructor(fields?: any[]);
+    get length(): number;
+    /**
+     * Appends fields; a field whose id matches an existing entry replaces it
+     * in place (position preserved), matching PocketBase upsert semantics.
+     */
+    add(...fields: any[]): void;
+    /**
+     * Inserts fields at a position. A field with an already-present id is
+     * moved: the old entry is removed first, then the field is inserted at
+     * the requested position.
+     */
+    addAt(position: number, ...fields: any[]): void;
+    removeById(id: string): void;
+    removeByName(name: string): void;
+    getById(id: string): Field | undefined;
+    getByName(name: string): Field | undefined;
+    at(index: number): Field | undefined;
+    find(predicate: (field: Field, index: number) => boolean): Field | undefined;
+    filter(predicate: (field: Field, index: number) => boolean): Field[];
+    map<T>(mapper: (field: Field, index: number) => T): T[];
+    forEach(callback: (field: Field, index: number) => void): void;
+    [Symbol.iterator](): Iterator<Field>;
+    /** Replaces the whole list (used by unmarshal({fields: [...]}, collection)) */
+    replaceAll(fields: any[]): void;
+    /** Plain objects, in order */
+    serialize(): Record<string, any>[];
+    private indexOfId;
+}
+
+/**
+ * Runtime Collection class matching the PocketBase JSVM global
+ *
+ * `new Collection({...})` in a migration produces one of these. All data
+ * properties are copied verbatim (auth options, templates, etc. survive a
+ * snapshot import round-trip); `fields` becomes a live FieldsList and
+ * `indexes` a real array so `push`/`findIndex`/`splice` work natively.
+ *
+ * No rule properties are defaulted: the serialized collection must contain
+ * exactly what the migration declared, so engine output stays byte-parity
+ * with static analysis of the same literals.
+ */
+
+declare function generateRuntimeCollectionId(): string;
+declare class Collection {
+    [key: string]: any;
+    id: string;
+    name: string;
+    type: string;
+    system: boolean;
+    fields: FieldsList;
+    indexes: string[];
+    constructor(data?: RawCollection);
+    /** PocketBase-shaped plain object (what a snapshot array entry looks like) */
+    serialize(): RawCollection;
+}
+
+/**
+ * Record simulation — an in-memory row store per collection
+ *
+ * Schema reconstruction never needs this: a migration that seeds or rewrites
+ * data does not change the shape of a collection. It matters for the other
+ * job the engine can do — running a hand-written data migration before it
+ * touches production and seeing what it actually does.
+ *
+ * Enabled with `records: "simulate"`. Left off, `Record` and the data-layer
+ * `app.*` methods stay the inert stubs they have always been, so schema-only
+ * replay is unchanged.
+ *
+ * The store lives on `CollectionStore`, which means it inherits the runner's
+ * transaction semantics for free: a migration that throws halfway through a
+ * data rewrite leaves neither schema nor records behind.
+ */
+
+/** PocketBase record ids are 15 lowercase alphanumeric characters */
+declare function generateRecordId(): string;
+/**
+ * The `Record` global a migration sees. Mirrors `core.Record`'s JSVM surface:
+ * `get`/`set` plus the typed getters, `load`, `publicExport`, `originalCopy`.
+ *
+ * Arbitrary property access (`record.title`) is deliberately *not* supported —
+ * `core.Record` is a Go struct and does not support it either, so a migration
+ * that relies on it would fail in PocketBase.
+ */
+declare class RecordModel {
+    private data;
+    private original;
+    private readonly owner;
+    /** Set by setPassword(); PocketBase stores a hash, the simulation the value */
+    private password?;
+    constructor(collection: Collection, data?: Record<string, unknown>);
+    get id(): string;
+    set id(value: string);
+    collection(): Collection;
+    /** PocketBase names a collection's table after the collection */
+    tableName(): string;
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    getString(key: string): string;
+    getBool(key: string): boolean;
+    getInt(key: string): number;
+    getFloat(key: string): number;
+    getDateTime(key: string): string;
+    getStringSlice(key: string): string[];
+    /** Bulk assignment, as `record.load({...})` does in the JSVM */
+    load(data: Record<string, unknown>): void;
+    setPassword(password: string): void;
+    validatePassword(password: string): boolean;
+    /** The record as it was last read from (or written to) the store */
+    originalCopy(): RecordModel;
+    /**
+     * Deep, independent copy. `owner` rebinds the copy to another Collection
+     * instance (what a transaction clone needs); everything the getters cannot
+     * reach — the pre-modification `original` and the password `setPassword()`
+     * stored — is carried over, so a copy behaves like the record it came from.
+     */
+    clone(owner?: Collection): RecordModel;
+    /** Plain object, the shape `publicExport()` returns in the JSVM */
+    publicExport(): Record<string, unknown>;
+    /** Every stored value, including system columns */
+    export(): Record<string, unknown>;
+    /** Called by the store once a save has committed */
+    markPersisted(): void;
+    /** Fields the record carries that the collection does not declare */
+    undeclaredFields(): string[];
+}
+/**
+ * Rows, keyed by collection id then record id. Insertion order is preserved
+ * so unsorted queries come back the way they went in.
+ */
+declare class RecordStore {
+    private byCollection;
+    save(record: RecordModel): RecordModel;
+    delete(record: RecordModel): boolean;
+    deleteById(collectionId: string, recordId: string): boolean;
+    getById(collectionId: string, recordId: string): RecordModel | undefined;
+    list(collectionId: string): RecordModel[];
+    count(collectionId: string): number;
+    /** Drops every row of a collection (what deleting the collection does) */
+    dropCollection(collectionId: string): void;
+    /** Every collection id that currently holds at least one record */
+    collectionIds(): string[];
+    /**
+     * Deep copy. Records are rebound to the collections in `collections` so a
+     * cloned record's `collection()` points at the cloned schema, not the one
+     * the transaction started from.
+     */
+    clone(resolveCollection: (id: string) => Collection | undefined): RecordStore;
+    /** Commit: adopt another store's rows */
+    replaceWith(other: RecordStore): void;
+    private rowsFor;
+}
+
+/**
+ * CollectionStore — the in-memory database state migrations execute against
+ *
+ * Keyed by collection id (migrations reference collections by id, name, or
+ * the `_pb_users_auth_` alias; renames must not orphan entries). Cloning
+ * serializes to plain objects and rebuilds, giving transaction semantics:
+ * the runner clones, applies a migration to the clone, and commits with
+ * replaceWith() only on success.
+ */
+
+declare class CollectionStore {
+    private byId;
+    /**
+     * Rows, when record simulation is enabled. Always present so clone/commit
+     * carry data through the same transaction as the schema; empty and
+     * effectively free when only schema is being replayed.
+     */
+    readonly records: RecordStore;
+    list(): Collection[];
+    getById(id: string): Collection | undefined;
+    getByNameOrId(nameOrId: string): Collection | undefined;
+    upsert(collection: Collection): void;
+    removeById(id: string): boolean;
+    /** Deep, independent copy (rebuilds Collection/FieldsList instances) */
+    clone(): CollectionStore;
+    /** Commit: adopt another store's state */
+    replaceWith(other: CollectionStore): void;
+    serialize(): RawCollection[];
+    /** Convert to the internal schema model used by diff/compare */
+    toSnapshot(): SchemaSnapshot;
+}
+
+/**
+ * Execution engine types
+ *
+ * The engine executes PocketBase JS migration files in a sandboxed context
+ * that emulates the PocketBase JSVM (goja) API surface, instead of statically
+ * parsing them. These types describe its configuration and results.
+ */
+
+/**
+ * A PocketBase-shaped plain collection object, as found in migration files
+ * and snapshot arrays (the JSON shape PocketBase itself serializes).
+ */
+type RawCollection = Record<string, any>;
+/**
+ * How the engine treats PocketBase APIs it does not simulate
+ * ($os, $dbx, Record, data-layer app methods, ...):
+ * - "lenient": record a warning and return an inert no-op value
+ * - "strict": throw immediately
+ */
+type EngineStrictness = "strict" | "lenient";
+/**
+ * Whether record CRUD and `$dbx`/`app.db()` queries execute against an
+ * in-memory row store:
+ * - "stub" (default): `Record` and the data-layer `app.*` methods stay inert,
+ *   which is all schema reconstruction needs
+ * - "simulate": rows are tracked per collection, so a hand-written data
+ *   migration can be executed and inspected before it runs for real
+ */
+type EngineRecordMode = "stub" | "simulate";
+interface EngineWarning {
+    /** Migration file the warning originated from, when known */
+    file?: string;
+    kind: "unsupported-api" | "console" | "noop";
+    /** The API that was stubbed, e.g. "$os.getenv" or "app.findRecordById" */
+    api?: string;
+    message: string;
+}
+interface EngineOptions {
+    /** Defaults to "lenient" */
+    strictness?: EngineStrictness;
+    /** Defaults to "stub" */
+    records?: EngineRecordMode;
+    /** Invoked for every warning as it happens (warnings are also collected) */
+    onWarning?: (warning: EngineWarning) => void;
+    /** Per-file evaluation/execution timeout in milliseconds. Defaults to 5000. */
+    timeoutMs?: number;
+}
+/** Which of a migration's two closures was executed */
+type MigrationDirection = "up" | "down";
+interface MigrationExecutionResult {
+    file?: string;
+    /** Which closure ran. Defaults to "up" for state reconstruction. */
+    direction: MigrationDirection;
+    /**
+     * False when the file registered no closure for this direction — no
+     * migrate() call at all, or a migrate(up) with no down.
+     */
+    applied: boolean;
+    warnings: EngineWarning[];
+}
+interface ReplayResult {
+    /** Final state converted to the internal schema model */
+    snapshot: SchemaSnapshot;
+    /** The raw store, for further execution or inspection */
+    store: CollectionStore;
+    warnings: EngineWarning[];
+    filesExecuted: string[];
+    /**
+     * How the file list was chosen — including anything on disk that is not
+     * applied, and anything applied that is no longer on disk. Null when the
+     * caller supplied the file list directly.
+     */
+    plan: MigrationPlan | null;
+}
+
+export { APPLIED_MIGRATIONS_TABLE as A, BoolField as B, CollectionStore as C, type DiscoveredMigration as D, type EngineOptions as E, FIELD_CONSTRUCTORS as F, Field as G, FileField as H, GeoPointField as I, JSONField as J, PasswordField as K, RelationField as L, type MigrationDirection as M, NumberField as N, FieldsList as O, POCKETBASE_DATABASE_FILENAME as P, generateRecordId as Q, RecordModel as R, SelectField as S, TextField as T, URLField as U, AppliedMigrationsError as a, RecordStore as b, appliedMigrationsFromList as c, defaultDataDirectory as d, discoverMigrations as e, extractTimestampFromFilename as f, readAppliedMigrationsIfPresent as g, resolveDatabasePath as h, type AppliedMigration as i, type AppliedMigrationsSource as j, type EngineRecordMode as k, type EngineStrictness as l, type EngineWarning as m, type MigrationExecutionResult as n, type MigrationPlan as o, planMigrationReplay as p, type PlanOptions as q, readAppliedMigrations as r, type ReplayResult as s, Collection as t, type RawCollection as u, generateRuntimeCollectionId as v, AutodateField as w, DateField as x, EditorField as y, EmailField as z };