@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/providers/SqliteJobStateProvider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Scheduled-job state in the application database (#1714). See `jobState.ts`.
+ *
+ * Uses the one connection `DatabaseManager.getHandle()` hands out — never a
+ * database file of its own — so it is encrypted when the database is
+ * (SQLCipher, `NGDPBASE_DATABASE_KEY`). The tables come from the core
+ * migration ledger (`databaseMigrations.ts`, 20261008180000).
+ *
+ * A lock is a row in `job_leases`, taken by one conditional write: insert it,
+ * or overwrite it only when it has expired or already belongs to the caller.
+ * SQLite runs that statement as one unit, so of any servers racing for a slot
+ * exactly one sees its row change.
+ *
+ * @module providers/SqliteJobStateProvider
+ */
+import type Database from 'better-sqlite3-multiple-ciphers';
+import { type JobRunRecord, type JobState, type JobStateLimits, type JobStateProvider } from './jobState.js';
+type Handle = InstanceType<typeof Database>;
+export interface SqliteJobStateOptions extends JobStateLimits {
+    /** For tests: the clock. */
+    now?: () => number;
+}
+declare class SqliteJobStateProvider implements JobStateProvider {
+    private readonly db;
+    readonly backend: "sqlite";
+    private readonly historyLimit;
+    private readonly checkpointMaxBytes;
+    private readonly now;
+    constructor(db: Handle, options?: SqliteJobStateOptions);
+    getState(jobId: string): Promise<JobState | null>;
+    putState(state: JobState): Promise<void>;
+    recordRun(jobId: string, run: JobRunRecord): Promise<void>;
+    listRuns(jobId: string): Promise<JobRunRecord[]>;
+    saveCheckpoint(jobId: string, runId: string, data: unknown): Promise<void>;
+    loadCheckpoint(jobId: string, runId: string): Promise<unknown>;
+    clearCheckpoint(jobId: string, runId: string): Promise<void>;
+    takeLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    renewLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
+}
+export default SqliteJobStateProvider;

package/lib/src/providers/databaseMigrations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The application database's migration ledger (#1536), strictly ascending by
+ * id (YYYYMMDDHHMMSS). Each entry is a frozen snapshot of what it did on its
+ * date; see `sqliteMigrations.ts`.
+ */
+import type { Migration } from './sqliteMigrations.js';
+declare const DATABASE_MIGRATIONS: Migration[];
+export default DATABASE_MIGRATIONS;

package/lib/src/providers/databaseMigrations.js

@@ -0,0 +1,47 @@
+const DATABASE_MIGRATIONS = [
+    {
+        // #1714: scheduled-job state, history, checkpoints and slot locks.
+        id: '20261008180000',
+        description: 'scheduled jobs: job_state, job_runs, job_checkpoints, job_leases',
+        up: (db) => {
+            db.exec(`CREATE TABLE job_state (
+        job_id TEXT PRIMARY KEY,
+        last_slot_done TEXT,
+        next_slot TEXT,
+        current_run TEXT,
+        updated_at TEXT NOT NULL
+      )`);
+            db.exec(`CREATE TABLE job_runs (
+        run_id TEXT PRIMARY KEY,
+        job_id TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        record TEXT NOT NULL
+      )`);
+            db.exec('CREATE INDEX job_runs_by_job ON job_runs (job_id, started_at)');
+            db.exec(`CREATE TABLE job_checkpoints (
+        job_id TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        data TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (job_id, run_id)
+      )`);
+            db.exec(`CREATE TABLE job_leases (
+        job_id TEXT NOT NULL,
+        slot TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        expires_at INTEGER NOT NULL,
+        PRIMARY KEY (job_id, slot)
+      )`);
+        }
+    },
+    {
+        // #1715: the schedule a job's slots were computed from, so a rule changed
+        // while the server was down is recomputed rather than caught up.
+        id: '20261009140000',
+        description: 'scheduled jobs: job_state.rule',
+        up: (db) => {
+            db.exec('ALTER TABLE job_state ADD COLUMN rule TEXT');
+        }
+    }
+];
+export default DATABASE_MIGRATIONS;

package/lib/src/providers/jobState.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Where scheduled jobs keep what must survive a restart (#1714, epic #1611):
+ * each job's last slot done, its next slot and its current run, a capped run
+ * history, a run's checkpoint, and the lock that lets exactly one server run a
+ * slot.
+ *
+ * Two backends, one contract (`__tests__/jobStateContract.ts` runs against
+ * both):
+ *   - `file` — JSON in FAST_STORAGE, written atomically; a lock is a file
+ *     created exclusively;
+ *   - `sqlite` — tables in the application database (DatabaseManager), changed
+ *     in transactions; a lock is a row taken by a conditional write.
+ *
+ * `selectJobStateBackend` reads `ngdpbase.jobs.state.provider`: `auto` picks
+ * `sqlite` when the application database is open, else `file`. Switching
+ * backends carries nothing across: the new one starts empty, next slots are
+ * recomputed and missed slots are not caught up.
+ *
+ * @module providers/jobState
+ */
+import type { JobContext } from '../context/JobContext.js';
+/** One run of a job. Times are ISO 8601 instants. */
+export interface JobRunRecord {
+    runId: string;
+    /** The slot this run is for; null for a run someone started by hand. */
+    slot: string | null;
+    startedAt: string;
+    /** 1 for the first try; a run resumed after a restart counts up. */
+    attempt: number;
+    /** `skipped`: a slot the scheduler passed over, by its catch-up or overlap rule (#1715). */
+    status: 'running' | 'completed' | 'failed' | 'interrupted' | 'skipped';
+    completedAt?: string;
+    error?: string;
+    /** A failed attempt with attempts left: when it is tried again (#1716). */
+    retryAt?: string;
+    /**
+     * Who asked, for a run started by hand (#1746): the run is restarted as
+     * them after a restart, or reported to them. `null` for a scheduled slot,
+     * which runs as the system principal — said on purpose (#1399), never left
+     * out. A record written before this field existed reads as having none.
+     */
+    requestedBy: JobContext | null;
+}
+export interface JobState {
+    jobId: string;
+    lastSlotDone: string | null;
+    /** The first slot not yet handled: run, skipped or failed (#1715). */
+    nextSlot: string | null;
+    current: JobRunRecord | null;
+    /**
+     * The schedule the slots were computed from (`rrule|dtstart|timeZone`), so a
+     * rule changed while the server was down is seen at the next start: slots
+     * are recomputed from then, and nothing is caught up for the old rule
+     * (#1715). Null for state written before the rule was kept.
+     */
+    rule: string | null;
+}
+export interface JobStateLimits {
+    /** Runs kept per job (`ngdpbase.jobs.history-limit`). Default 50. */
+    historyLimit?: number;
+    /** Largest checkpoint accepted, in bytes of JSON. Default 256 KiB. */
+    checkpointMaxBytes?: number;
+}
+export declare const DEFAULT_HISTORY_LIMIT = 50;
+export declare const DEFAULT_CHECKPOINT_MAX_BYTES: number;
+export interface JobStateProvider {
+    readonly backend: 'file' | 'sqlite';
+    getState(jobId: string): Promise<JobState | null>;
+    putState(state: JobState): Promise<void>;
+    /** Add or replace a run in the job's history, keeping the newest `historyLimit`. */
+    recordRun(jobId: string, run: JobRunRecord): Promise<void>;
+    /** The job's runs, newest first. */
+    listRuns(jobId: string): Promise<JobRunRecord[]>;
+    /** Throws when the JSON is larger than `checkpointMaxBytes`. */
+    saveCheckpoint(jobId: string, runId: string, data: unknown): Promise<void>;
+    loadCheckpoint(jobId: string, runId: string): Promise<unknown>;
+    clearCheckpoint(jobId: string, runId: string): Promise<void>;
+    /**
+     * Take the lock for one slot, or steal it when its holder let it expire.
+     * True for exactly one caller among any that contend.
+     */
+    takeLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Extend a lock this owner holds. False when it no longer holds it. */
+    renewLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Give up a lock this owner holds; a lock held by another owner is left alone. */
+    releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
+    close?(): void;
+}
+export declare function assertJobId(jobId: string): void;
+/** A slot as a compact UTC stamp, safe in a file name: `20261008T060000Z`. */
+export declare function slotKey(slot: string): string;
+/** The JSON a checkpoint is stored as, refused when larger than the cap. */
+export declare function checkpointJson(data: unknown, maxBytes: number): string;
+/**
+ * Which backend `ngdpbase.jobs.state.provider` names. `auto` (the default)
+ * picks `sqlite` when the application database is open. `sqlite` with no
+ * database open is an error naming the key to set.
+ */
+export declare function selectJobStateBackend(configured: unknown, databaseEnabled: boolean): 'file' | 'sqlite';

package/lib/src/providers/lunrQueryToMiniSearch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lunr-style query strings, read as MiniSearch query trees (#1736).
+ *
+ * The search provider moved from Lunr to MiniSearch, but its callers still
+ * speak Lunr's query language: the field-scoped search builds `+title:word`,
+ * type-ahead appends `*` to the last term (`applyPrefixToLastTerm`), and a
+ * person may type any of it into the search box. This keeps that language,
+ * with the same meaning:
+ *
+ *   word          an optional term; with no required terms, any one matches
+ *   +word         required: every result contains it
+ *   -word         excluded: no result contains it
+ *   field:word    only that field (an unknown field is read as plain text, so
+ *                 a typed URL such as `https://x` is a search, not an error)
+ *   word*         prefix match
+ *   word~1        fuzzy match, up to that edit distance
+ *
+ * A term's `^boost` is accepted and ignored. When required terms are present,
+ * optional terms no longer narrow the results (as in Lunr); they are not used
+ * for ranking either.
+ *
+ * @module providers/lunrQueryToMiniSearch
+ */
+import { type Query } from 'minisearch';
+/**
+ * The MiniSearch query for a Lunr-style string, or null when the string holds
+ * nothing to search for.
+ *
+ * @param query  - the query as a caller or a person wrote it
+ * @param fields - the indexed field names; a `field:` prefix naming another is plain text
+ */
+export declare function lunrQueryToMiniSearch(query: string, fields: readonly string[]): Query | null;

package/lib/src/providers/mediaFilenameDate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Conservative filename → capture-date parser (#809, slice C of #807).
+ *
+ * Last-resort fallback used by media providers when a file carries no usable
+ * EXIF/QuickTime capture date. Many devices encode the capture time in the
+ * filename (e.g. `PXL_20260113_123414708.jpg`, `2026-04-03-IMG_4654.jpg`,
+ * `Feb_20_2026_19_25_04.jpg`); without this, those files index with
+ * `dateTimeOriginal: null` and sort only by file `mtime`.
+ *
+ * Design constraints (from the issue):
+ *   - **Conservative** — only a small set of high-confidence, anchored patterns
+ *     are accepted. Anything ambiguous returns `null`, and the caller then
+ *     falls back to `mtime` and surfaces the file to admins.
+ *   - **Distinguishable provenance** — the caller records that the resulting
+ *     date came from the filename (`captureDateSource: 'filename'`), so a
+ *     parsed date never masquerades as authoritative EXIF metadata.
+ *
+ * Returns a `"YYYY-MM-DD HH:MM:SS"` string (the exact shape produced by the
+ * EXIF extractor, so it flows through sort/filter identically), or `null`.
+ * A date-only match yields a `00:00:00` time.
+ */
+export declare function parseDateFromFilename(filename: string): string | null;

package/lib/src/providers/sqliteBackup.d.ts

@@ -0,0 +1,128 @@
+import type DatabaseConstructor from 'better-sqlite3-multiple-ciphers';
+/**
+ * The SQLite driver, handed in rather than imported: the worker loads it from
+ * the file the site's own thread resolved (`job.driver`), so both threads use
+ * the same native module, and a worker run from source (tsx) is not sent to
+ * the type declarations tsconfig's `paths` maps the package name to.
+ */
+export type Driver = typeof DatabaseConstructor;
+/** One database to copy into a backup: where it is, the key it opens under ('' = plaintext), and the backup file to write. */
+export interface DatabaseExport {
+    name: string;
+    source: string;
+    sourceKey: string;
+    target: string;
+}
+export interface ExportOutcome {
+    written: Array<{
+        name: string;
+        target: string;
+        sizeBytes: number;
+        tables: number;
+    }>;
+    /** Databases that could not be copied; the others still are. Each is named, never dropped silently. */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** One database to stage from a backup: the backup's file, and the live file it will replace at the next start. */
+export interface DatabaseStage {
+    name: string;
+    backupFile: string;
+    live: string;
+    targetKey: string;
+}
+export interface StageOutcome {
+    staged: Array<{
+        name: string;
+        staged: string;
+        live: string;
+        tables: number;
+    }>;
+}
+export type SqliteBackupJob = {
+    kind: 'export';
+    exports: DatabaseExport[];
+    backupKey: string;
+} | {
+    kind: 'stage';
+    stages: DatabaseStage[];
+    backupKey: string;
+};
+/** A job as the worker receives it: with the driver's resolved file. */
+export type WorkerJob = SqliteBackupJob & {
+    driver: string;
+};
+/** The staged file for a live database: beside it, so staging and applying name the same path. */
+export declare const stagedPath: (live: string) => string;
+/**
+ * Write an encrypted copy of each database under `backupKey`. A database that
+ * cannot be opened or copied is named in `failed`, its partial file removed;
+ * the others are still written. A target that already exists is never
+ * overwritten.
+ */
+export declare function exportDatabasesSync(Database: Driver, exports: DatabaseExport[], backupKey: string): ExportOutcome;
+/**
+ * Stage a restore: each backup file is opened under the backup key,
+ * integrity-checked, and copied into `<live>.staged` under the target
+ * database's key, which is then opened and checked too. All or nothing: if
+ * any database fails, every staged file is removed and the error names it.
+ * Live files are never touched.
+ */
+export declare function stageDatabasesSync(Database: Driver, stages: DatabaseStage[], backupKey: string): StageOutcome;
+/** Run a job of this module on a worker thread, so a large database never stalls requests or the liveness probe. */
+export declare function runOffThread(job: {
+    kind: 'export';
+    exports: DatabaseExport[];
+    backupKey: string;
+}, timeoutMs: number): Promise<ExportOutcome>;
+export declare function runOffThread(job: {
+    kind: 'stage';
+    stages: DatabaseStage[];
+    backupKey: string;
+}, timeoutMs: number): Promise<StageOutcome>;
+/** What a staged restore is: written last, once every database is staged; its presence is what the next start applies. */
+export interface StagedRestoreManifest {
+    version: 1;
+    stagedAt: string;
+    /** When the backup it came from was taken. */
+    backup: string;
+    /** The backup document's filename. */
+    source: string;
+    /** Who staged it: the account named by the request's context. */
+    stagedBy: string;
+    /** The backup of the live data taken just before staging (D6): what to restore to undo this one. */
+    safetyBackup?: string;
+    databases: Array<{
+        name: string;
+        live: string;
+        staged: string;
+    }>;
+}
+/** Where the manifest of a staged restore lives: beside the application database. */
+export declare const manifestPath: (applicationFile: string) => string;
+export declare function writeManifest(file: string, manifest: StagedRestoreManifest): void;
+export interface ApplyOutcome {
+    /** Databases now on the restored copy, each with where its previous file was kept. */
+    applied: Array<{
+        name: string;
+        live: string;
+        kept: string;
+    }>;
+    /** Why nothing was applied; the staged files were set aside as `*.incomplete`. */
+    refused?: string;
+}
+/**
+ * Apply a staged restore at start, before any database opens. Each live file,
+ * with its `-wal` and `-shm`, steps aside as `*.pre-restore` (`-wal`/`-shm`
+ * beside it, so the kept copy still opens as it was), and the staged file
+ * takes its name. A rename, never a write into a live database.
+ *
+ * All or nothing: if any database the manifest names is not staged, nothing
+ * is applied; what is staged is renamed `*.incomplete`, so it is neither
+ * applied nor retried. A staged file with no manifest (staging was
+ * interrupted) is set aside the same way. `allowed` says which live paths may
+ * be replaced, so a tampered manifest cannot rename an arbitrary file.
+ */
+export declare function applyStagedRestore(applicationFile: string, allowed: (live: string) => boolean): ApplyOutcome | null;