@minnowdb/core 0.2.1 → 0.4.0

package/dist/storage/persistence.d.ts

@@ -0,0 +1,37 @@
+/** How an application wants the browser to treat origin-level eviction protection. */
+export type OriginPersistencePolicy = "best-effort" | "request" | "required";
+export type OriginPersistenceReason = "already-persisted" | "granted" | "denied" | "unsupported" | "unavailable";
+export interface OriginPersistenceStatus {
+    /** The policy that was evaluated. */
+    policy: OriginPersistencePolicy;
+    /** Whether the browser currently reports this origin as protected from automatic eviction. */
+    persisted: boolean;
+    /** Whether this call asked the browser to grant persistence. */
+    requested: boolean;
+    /** Why `persisted` has its current value. */
+    reason: OriginPersistenceReason;
+}
+/**
+ * The browser declined or could not provide eviction protection required by the application.
+ *
+ * This is separate from adapter durability. Strict IndexedDB/OPFS commits protect against torn
+ * or reordered writes; only the browser can protect an entire origin from quota eviction.
+ */
+export declare class OriginPersistenceRequiredError extends Error {
+    readonly name = "OriginPersistenceRequiredError";
+}
+interface PersistenceStorageManager {
+    persisted?: () => Promise<boolean>;
+    persist?: () => Promise<boolean>;
+}
+/**
+ * Checks or requests browser-managed protection from whole-origin eviction.
+ *
+ * Call this from a user gesture before opening a durable store when losing the entire origin is
+ * unacceptable. `best-effort` only inspects existing protection, `request` asks when possible,
+ * and `required` rejects unless protection is already present or is granted now.
+ *
+ * The optional storage manager exists for deterministic tests and non-browser wrappers.
+ */
+export declare function ensureOriginPersistence(policy?: OriginPersistencePolicy, storageManager?: PersistenceStorageManager | undefined): Promise<OriginPersistenceStatus>;
+export {};

package/dist/storage/persistence.js

@@ -0,0 +1,78 @@
+/**
+ * The browser declined or could not provide eviction protection required by the application.
+ *
+ * This is separate from adapter durability. Strict IndexedDB/OPFS commits protect against torn
+ * or reordered writes; only the browser can protect an entire origin from quota eviction.
+ */
+export class OriginPersistenceRequiredError extends Error {
+    name = "OriginPersistenceRequiredError";
+}
+function defaultStorageManager() {
+    if (typeof navigator === "undefined")
+        return undefined;
+    return navigator.storage;
+}
+/**
+ * Checks or requests browser-managed protection from whole-origin eviction.
+ *
+ * Call this from a user gesture before opening a durable store when losing the entire origin is
+ * unacceptable. `best-effort` only inspects existing protection, `request` asks when possible,
+ * and `required` rejects unless protection is already present or is granted now.
+ *
+ * The optional storage manager exists for deterministic tests and non-browser wrappers.
+ */
+export async function ensureOriginPersistence(policy = "request", storageManager = defaultStorageManager()) {
+    const runtimePolicy = policy;
+    if (runtimePolicy !== "best-effort" &&
+        runtimePolicy !== "request" &&
+        runtimePolicy !== "required") {
+        throw new TypeError(`Unknown origin persistence policy: ${policy}`);
+    }
+    if (storageManager?.persisted === undefined) {
+        if (policy === "required") {
+            throw new OriginPersistenceRequiredError("Persistent origin storage is required, but the StorageManager persistence API is unavailable");
+        }
+        return { policy, persisted: false, requested: false, reason: "unsupported" };
+    }
+    let alreadyPersisted;
+    try {
+        alreadyPersisted = await storageManager.persisted();
+    }
+    catch (error) {
+        if (policy === "required") {
+            throw new OriginPersistenceRequiredError("Persistent origin storage is required, but its status could not be read", { cause: error });
+        }
+        return { policy, persisted: false, requested: false, reason: "unavailable" };
+    }
+    if (alreadyPersisted) {
+        return { policy, persisted: true, requested: false, reason: "already-persisted" };
+    }
+    if (policy === "best-effort") {
+        return { policy, persisted: false, requested: false, reason: "denied" };
+    }
+    if (storageManager.persist === undefined) {
+        if (policy === "required") {
+            throw new OriginPersistenceRequiredError("Persistent origin storage is required, but this browser cannot request it");
+        }
+        return { policy, persisted: false, requested: false, reason: "unsupported" };
+    }
+    let granted;
+    try {
+        granted = await storageManager.persist();
+    }
+    catch (error) {
+        if (policy === "required") {
+            throw new OriginPersistenceRequiredError("Persistent origin storage is required, but the browser rejected the request", { cause: error });
+        }
+        return { policy, persisted: false, requested: true, reason: "unavailable" };
+    }
+    if (!granted && policy === "required") {
+        throw new OriginPersistenceRequiredError("Persistent origin storage is required, but the browser denied the request");
+    }
+    return {
+        policy,
+        persisted: granted,
+        requested: true,
+        reason: granted ? "granted" : "denied",
+    };
+}

package/dist/storage/snapshot-stream.d.ts

@@ -0,0 +1,24 @@
+import { type SnapshotFrame, type SnapshotFrameFooter, type SnapshotFrameKind, type SnapshotFrameStreamHeader, type SnapshotMetadataItem } from "./types.js";
+export type SnapshotFrameStreamEntry = {
+    readonly type: "header";
+    readonly header: SnapshotFrameStreamHeader;
+} | {
+    readonly type: "frame";
+    readonly frame: SnapshotFrame;
+} | {
+    readonly type: "footer";
+    readonly footer: SnapshotFrameFooter;
+};
+export declare function prepareSnapshotFrameStreamHeader(input: SnapshotFrameStreamHeader): SnapshotFrameStreamHeader;
+export declare function encodeSnapshotFrameStreamHeader(header: SnapshotFrameStreamHeader): Uint8Array;
+export declare function snapshotFrameStreamHeaderIdentity(header: SnapshotFrameStreamHeader): string;
+export declare function snapshotFrameEnvelopeParts(frame: SnapshotFrame): readonly Uint8Array[];
+export declare function extendSnapshotFrameStreamChecksum(checksum: number, parts: readonly Uint8Array[]): number;
+export declare function encodeSnapshotFrameStreamFooter(footer: SnapshotFrameFooter): Uint8Array;
+/** Canonical substrate-independent encoding for one bounded metadata page. */
+export declare function encodeSnapshotMetadataPage(items: readonly unknown[]): Uint8Array;
+export declare function decodeSnapshotMetadataPage(payload: Uint8Array): unknown[];
+/** Decodes and strictly validates one canonical metadata frame before durable staging. */
+export declare function decodeSnapshotMetadataItems(kind: Exclude<SnapshotFrameKind, "block">, payload: Uint8Array): SnapshotMetadataItem[];
+/** Parses and verifies the bounded framed snapshot container without retaining prior frames. */
+export declare function decodeSnapshotFrameStream(source: AsyncIterable<Uint8Array>): AsyncGenerator<SnapshotFrameStreamEntry>;