@peers-app/peers-sdk 0.30.0 → 0.30.2

package/dist/data/derived-row-id.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DERIVED_ROW_ID_PREFIX = void 0;
+exports.derivedRowId = derivedRowId;
+exports.isDerivedRowId = isDerivedRowId;
+/**
+ * Row ids derived from a row's own values, the same on every device. `Files` is the first user;
+ * a later `defineTable({ idFrom })` declaration derives its ids the same way, so no id changes.
+ *
+ * Kept free of heavy imports, like `signed-row-id.ts`, so package code can compute them.
+ */
+const peer_id_1 = require("../peer-id");
+/**
+ * Leading characters of every derived row id. Every derived prefix starts `000`, while `newid()`
+ * ids start with their creation time, so the two can't collide.
+ */
+exports.DERIVED_ROW_ID_PREFIX = "000r";
+/**
+ * The id of a row derived from its values: a hash of `["row/1", tableName, values]` as JSON,
+ * after {@link DERIVED_ROW_ID_PREFIX}. The encoding is frozen: ids derived this way are stored
+ * on every device, so changing it would orphan them.
+ *
+ * The hash part is 21 base-36 characters (about 108 bits). Taking over an existing id needs a
+ * second preimage (about 2^108 work); crafting two rows with one id costs about 2^54.
+ *
+ * @param tableName - The table's name.
+ * @param values - The values the id is derived from, in a fixed order.
+ * @throws When a value isn't a string, a finite number or a boolean.
+ */
+function derivedRowId(tableName, values) {
+    for (const value of values) {
+        if (typeof value !== "string" &&
+            typeof value !== "boolean" &&
+            !(typeof value === "number" && Number.isFinite(value))) {
+            throw new Error(`Table ${tableName}: a derived id's values must be strings, numbers or booleans`);
+        }
+    }
+    return (0, peer_id_1.deterministicPeerId)(exports.DERIVED_ROW_ID_PREFIX, JSON.stringify(["row/1", tableName, values]));
+}
+/**
+ * Whether `id` has the form of a {@link derivedRowId}: a hint, not a proof that it was derived.
+ *
+ * @param id - A candidate row id.
+ */
+function isDerivedRowId(id) {
+    return typeof id === "string" && id.length === 25 && id.startsWith(exports.DERIVED_ROW_ID_PREFIX);
+}

package/dist/data/files/chunk-store.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Where a device keeps file chunks, by hash. Each host supplies one store per account
+ * ({@link setChunkStore}): an encrypted SQLite database on Node hosts, IndexedDB in the browser.
+ * Chunks are deduplicated across the account's contexts: a chunk three groups list is stored once.
+ */
+/** One stored chunk, as {@link ChunkStore.list} describes it. */
+export interface IStoredChunk {
+    /** The chunk's SHA-256 hash, as `hashBytes` gives it. */
+    hash: string;
+    /** Its length in bytes. */
+    size: number;
+    /** When it was last stored, in milliseconds by this device's clock. */
+    storedAt: number;
+}
+/** A device's chunk storage for one account. */
+export interface ChunkStore {
+    /**
+     * Whether a chunk is stored.
+     *
+     * @param hash - The chunk's hash.
+     */
+    has(hash: string): Promise<boolean>;
+    /**
+     * A stored chunk's bytes.
+     *
+     * @param hash - The chunk's hash.
+     * @returns The bytes, or undefined when the chunk isn't stored.
+     */
+    get(hash: string): Promise<Uint8Array | undefined>;
+    /**
+     * Store a chunk. Storing one that's already there keeps its bytes and refreshes `storedAt`, so
+     * a new file reusing an old chunk protects it from a sweep.
+     *
+     * @param hash - The chunk's hash; the caller has checked it against the bytes.
+     * @param bytes - The chunk.
+     */
+    put(hash: string, bytes: Uint8Array): Promise<void>;
+    /**
+     * Delete chunks, each only if it was stored before `storedBefore`. The age check and the delete
+     * are one step, so a concurrent {@link put} that refreshes a chunk wins.
+     *
+     * @param hashes - The chunks to delete; missing ones are skipped.
+     * @param storedBefore - Keep any chunk stored at or after this time.
+     * @returns How many chunks were deleted.
+     */
+    delete(hashes: readonly string[], storedBefore: number): Promise<number>;
+    /**
+     * Delete on an already-open store without yielding, so collection's liveness check and
+     * deletion are one synchronous step. Node stores provide this; IndexedDB cannot.
+     */
+    deleteSync?(hashes: readonly string[], storedBefore: number): IChunkStoreStats;
+    /**
+     * A page of stored chunks, in hash order.
+     *
+     * @param opts.after - Start after this hash; from the first when omitted.
+     * @param opts.limit - Most chunks to return (default 1,000).
+     */
+    list(opts?: {
+        after?: string;
+        limit?: number;
+    }): Promise<IStoredChunk[]>;
+    /** How many chunks are stored, and their total size in bytes. */
+    stats(): Promise<IChunkStoreStats>;
+}
+/** A chunk store's totals. */
+export interface IChunkStoreStats {
+    /** Chunks stored. */
+    count: number;
+    /** Their total size in bytes. */
+    bytes: number;
+}
+/** Most chunks one {@link ChunkStore.list} page returns by default. */
+export declare const CHUNK_LIST_PAGE = 1000;
+/** A {@link ChunkStore} in memory, for tests and ephemeral hosts. */
+export declare class MemoryChunkStore implements ChunkStore {
+    private readonly now;
+    private readonly chunks;
+    /** @param now - The clock `storedAt` comes from. */
+    constructor(now?: () => number);
+    has(hash: string): Promise<boolean>;
+    get(hash: string): Promise<Uint8Array | undefined>;
+    put(hash: string, bytes: Uint8Array): Promise<void>;
+    delete(hashes: readonly string[], storedBefore: number): Promise<number>;
+    /** Delete without yielding, using the same age check as the persistent Node store. */
+    deleteSync(hashes: readonly string[], storedBefore: number): IChunkStoreStats;
+    list(opts?: {
+        after?: string;
+        limit?: number;
+    }): Promise<IStoredChunk[]>;
+    stats(): Promise<IChunkStoreStats>;
+}
+/**
+ * Set this process's chunk store. Reads and writes waiting for one continue.
+ *
+ * @param store - The account's chunk store.
+ */
+export declare function setChunkStore(store: ChunkStore): void;
+/** This process's chunk store, once {@link setChunkStore} has set it. */
+export declare function getChunkStore(): Promise<ChunkStore>;
+/**
+ * Fetches a chunk this device lacks from a connected device, checks its hash and stores it.
+ * Resolves null when no device has it.
+ */
+export type ChunkDownloader = (hash: string) => Promise<Uint8Array | null>;
+/**
+ * Set how chunks this device lacks are fetched. peers-device installs the connection manager's.
+ *
+ * @param downloader - The downloader, or null for none.
+ */
+export declare function setChunkDownloader(downloader: ChunkDownloader | null): void;
+/**
+ * Fetch a chunk this device lacks from a connected device; the downloader stores it.
+ *
+ * @param hash - The chunk's hash.
+ * @returns The bytes, or null when no device has it or there's no downloader.
+ */
+export declare function downloadChunk(hash: string): Promise<Uint8Array | null>;
+/** Forget the chunk store and downloader (for tests). */
+export declare function resetChunkStore(): void;

package/dist/data/files/chunk-store.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Where a device keeps file chunks, by hash. Each host supplies one store per account
+ * ({@link setChunkStore}): an encrypted SQLite database on Node hosts, IndexedDB in the browser.
+ * Chunks are deduplicated across the account's contexts: a chunk three groups list is stored once.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryChunkStore = exports.CHUNK_LIST_PAGE = void 0;
+exports.setChunkStore = setChunkStore;
+exports.getChunkStore = getChunkStore;
+exports.setChunkDownloader = setChunkDownloader;
+exports.downloadChunk = downloadChunk;
+exports.resetChunkStore = resetChunkStore;
+/** Most chunks one {@link ChunkStore.list} page returns by default. */
+exports.CHUNK_LIST_PAGE = 1000;
+/** A {@link ChunkStore} in memory, for tests and ephemeral hosts. */
+class MemoryChunkStore {
+    now;
+    chunks = new Map();
+    /** @param now - The clock `storedAt` comes from. */
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    async has(hash) {
+        return this.chunks.has(hash);
+    }
+    async get(hash) {
+        return this.chunks.get(hash)?.bytes;
+    }
+    async put(hash, bytes) {
+        const stored = this.chunks.get(hash);
+        this.chunks.set(hash, { bytes: stored?.bytes ?? new Uint8Array(bytes), storedAt: this.now() });
+    }
+    async delete(hashes, storedBefore) {
+        return this.deleteSync(hashes, storedBefore).count;
+    }
+    /** Delete without yielding, using the same age check as the persistent Node store. */
+    deleteSync(hashes, storedBefore) {
+        const deleted = { count: 0, bytes: 0 };
+        for (const hash of hashes) {
+            const stored = this.chunks.get(hash);
+            if (stored && stored.storedAt < storedBefore) {
+                this.chunks.delete(hash);
+                deleted.count++;
+                deleted.bytes += stored.bytes.length;
+            }
+        }
+        return deleted;
+    }
+    async list(opts) {
+        const limit = opts?.limit ?? exports.CHUNK_LIST_PAGE;
+        return [...this.chunks.keys()]
+            .filter((hash) => opts?.after === undefined || hash > opts.after)
+            .sort()
+            .slice(0, limit)
+            .map((hash) => {
+            const { bytes, storedAt } = this.chunks.get(hash);
+            return { hash, size: bytes.length, storedAt };
+        });
+    }
+    async stats() {
+        let bytes = 0;
+        for (const chunk of this.chunks.values())
+            bytes += chunk.bytes.length;
+        return { count: this.chunks.size, bytes };
+    }
+}
+exports.MemoryChunkStore = MemoryChunkStore;
+let chunkStore = null;
+let chunkStoreWaiters = [];
+/**
+ * Set this process's chunk store. Reads and writes waiting for one continue.
+ *
+ * @param store - The account's chunk store.
+ */
+function setChunkStore(store) {
+    chunkStore = store;
+    const waiters = chunkStoreWaiters;
+    chunkStoreWaiters = [];
+    for (const resolve of waiters)
+        resolve(store);
+}
+/** This process's chunk store, once {@link setChunkStore} has set it. */
+function getChunkStore() {
+    if (chunkStore)
+        return Promise.resolve(chunkStore);
+    return new Promise((resolve) => chunkStoreWaiters.push(resolve));
+}
+let chunkDownloader = null;
+/**
+ * Set how chunks this device lacks are fetched. peers-device installs the connection manager's.
+ *
+ * @param downloader - The downloader, or null for none.
+ */
+function setChunkDownloader(downloader) {
+    chunkDownloader = downloader;
+}
+/**
+ * Fetch a chunk this device lacks from a connected device; the downloader stores it.
+ *
+ * @param hash - The chunk's hash.
+ * @returns The bytes, or null when no device has it or there's no downloader.
+ */
+async function downloadChunk(hash) {
+    return chunkDownloader ? chunkDownloader(hash) : null;
+}
+/** Forget the chunk store and downloader (for tests). */
+function resetChunkStore() {
+    chunkStore = null;
+    chunkStoreWaiters = [];
+    chunkDownloader = null;
+}

package/dist/data/files/file-read-stream.d.ts

@@ -1,8 +1,11 @@
 import { type IFile } from "./file.types";
-import type { FilesTable } from "./files";
+/**
+ * Reads one file's bytes chunk by chunk, from this device's chunks or, for a chunk it lacks, from
+ * a connected device. Each chunk is checked against its hash unless verification is skipped.
+ * Open one with {@link FilesTable.openReadStream}.
+ */
 export declare class FileReadStream {
     private fileRecord;
-    private fileTable;
     private preloadChunksCount;
     private skipVerification;
     private chunkHashes;
@@ -12,17 +15,43 @@ export declare class FileReadStream {
     private positionInChunk;
     private totalPosition;
     private eof;
-    constructor(fileRecord: IFile, fileTable: FilesTable, preloadChunksCount?: number, skipVerification?: boolean);
+    /**
+     * @param fileRecord - The file's row.
+     * @param preloadChunksCount - Chunks to fetch ahead of the reader, counting the current one.
+     * @param skipVerification - Skip hash checks (only for trusted local data).
+     */
+    constructor(fileRecord: IFile, preloadChunksCount?: number, skipVerification?: boolean);
     private loadChunkHashes;
     private loadChunkByIndex;
     private preloadChunks;
     private loadCurrentChunk;
+    /**
+     * Read the next bytes.
+     *
+     * @param size - Most bytes to read; one chunk's worth when omitted.
+     * @returns The bytes, or null at the end of the file.
+     */
     read(size?: number): Promise<Uint8Array | null>;
+    /**
+     * Move to a byte position; the next read starts there.
+     *
+     * @param position - From 0 to the file's size.
+     */
     seek(position: number): Promise<void>;
+    /** A copy of the file's row. */
     getMetadata(): IFile;
+    /** The byte position the next read starts at. */
     getPosition(): number;
+    /** The whole file's size in bytes. */
     getFileSize(): number;
+    /** Whether the stream is at the end of the file. */
     isEOF(): boolean;
+    /** Bytes between the position and the end of the file. */
     getBytesRemaining(): number;
+    /**
+     * Read the whole file from the start.
+     *
+     * @returns The bytes, or null when a chunk is missing everywhere or fails its hash check.
+     */
     readAll(): Promise<Uint8Array | null>;
 }

package/dist/data/files/file-read-stream.js

@@ -2,10 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileReadStream = void 0;
 const keys_1 = require("../../keys");
+const chunk_store_1 = require("./chunk-store");
 const file_types_1 = require("./file.types");
+/**
+ * Reads one file's bytes chunk by chunk, from this device's chunks or, for a chunk it lacks, from
+ * a connected device. Each chunk is checked against its hash unless verification is skipped.
+ * Open one with {@link FilesTable.openReadStream}.
+ */
 class FileReadStream {
     fileRecord;
-    fileTable;
     preloadChunksCount;
     skipVerification;
     chunkHashes = null;
@@ -15,9 +20,13 @@ class FileReadStream {
     positionInChunk = 0;
     totalPosition = 0;
     eof = false;
-    constructor(fileRecord, fileTable, preloadChunksCount = 2, skipVerification = false) {
+    /**
+     * @param fileRecord - The file's row.
+     * @param preloadChunksCount - Chunks to fetch ahead of the reader, counting the current one.
+     * @param skipVerification - Skip hash checks (only for trusted local data).
+     */
+    constructor(fileRecord, preloadChunksCount = 2, skipVerification = false) {
         this.fileRecord = fileRecord;
-        this.fileTable = fileTable;
         this.preloadChunksCount = preloadChunksCount;
         this.skipVerification = skipVerification;
     }
@@ -25,24 +34,19 @@ class FileReadStream {
         if (this.chunkHashes !== null) {
             return; // Already loaded
         }
-        if (this.fileRecord.chunkHashes) {
-            // Small file: chunk hashes stored directly in database
-            this.chunkHashes = this.fileRecord.chunkHashes;
-        }
-        else if (this.fileRecord.indexFileId) {
-            // Large file: chunk hashes stored in separate index file (recursively)
-            this.chunkHashes = await this.fileTable.loadChunkHashesRecursively(this.fileRecord.indexFileId);
-        }
-        else {
-            throw new Error(`File ${this.fileRecord.fileId} has neither chunkHashes nor indexFileId`);
+        const chunkHashes = this.fileRecord.chunkHashes ?? [];
+        if (chunkHashes.length === 0 && this.fileRecord.fileSize > 0) {
+            // Older builds kept a file over 1,000 chunks in index files, which are no longer read.
+            throw new Error(`File ${this.fileRecord.fileId} has no chunk list`);
         }
         if (!this.skipVerification) {
-            const computedFileHash = (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(this.chunkHashes)));
+            const computedFileHash = (0, file_types_1.fileHashOf)(chunkHashes);
             if (computedFileHash !== this.fileRecord.fileHash) {
                 throw new Error(`File integrity check failed for ${this.fileRecord.fileId}: ` +
                     `chunk hashes produce ${computedFileHash}, expected ${this.fileRecord.fileHash}`);
             }
         }
+        this.chunkHashes = chunkHashes;
     }
     async loadChunkByIndex(chunkIndex) {
         await this.loadChunkHashes();
@@ -51,19 +55,11 @@ class FileReadStream {
             throw new Error(`Chunk index ${chunkIndex} out of bounds`);
         }
         const chunkHash = chunkHashes[chunkIndex];
-        const ops = await (0, file_types_1.getFileOps)();
-        const chunkPath = `${file_types_1.CHUNKS_DIR}/${chunkHash}`;
-        let chunk;
-        if (await ops.fileExists(chunkPath)) {
-            // Read from local storage
-            chunk = await ops.readFile(chunkPath);
-        }
-        else {
-            // Download from peer by hash
-            chunk = (await ops.downloadFileChunk(chunkHash));
-            if (!chunk) {
-                throw new Error(`Chunk ${chunkHash} not found in storage or peers`);
-            }
+        const store = await (0, chunk_store_1.getChunkStore)();
+        // Stored here, or downloaded from a connected device (which stores it).
+        const chunk = (await store.get(chunkHash)) ?? (await (0, chunk_store_1.downloadChunk)(chunkHash));
+        if (!chunk) {
+            throw new Error(`Chunk ${chunkHash} not found in storage or peers`);
         }
         // Verify chunk integrity (skip for trusted local reads)
         if (!this.skipVerification) {
@@ -109,6 +105,12 @@ class FileReadStream {
         this.currentChunkBuffer = await chunkPromise;
         this.chunkPromises.delete(this.currentChunkIndex);
     }
+    /**
+     * Read the next bytes.
+     *
+     * @param size - Most bytes to read; one chunk's worth when omitted.
+     * @returns The bytes, or null at the end of the file.
+     */
     async read(size) {
         if (this.eof) {
             return null;
@@ -146,6 +148,11 @@ class FileReadStream {
         await this.preloadChunks();
         return chunks.length > 0 ? new Uint8Array(Buffer.concat(chunks)) : null;
     }
+    /**
+     * Move to a byte position; the next read starts there.
+     *
+     * @param position - From 0 to the file's size.
+     */
     async seek(position) {
         if (position < 0) {
             throw new Error("Seek position cannot be negative");
@@ -167,22 +174,31 @@ class FileReadStream {
         this.chunkPromises.clear();
         await this.preloadChunks();
     }
+    /** A copy of the file's row. */
     getMetadata() {
         return { ...this.fileRecord };
     }
+    /** The byte position the next read starts at. */
     getPosition() {
         return this.totalPosition;
     }
+    /** The whole file's size in bytes. */
     getFileSize() {
         return this.fileRecord.fileSize;
     }
+    /** Whether the stream is at the end of the file. */
     isEOF() {
         return this.eof;
     }
+    /** Bytes between the position and the end of the file. */
     getBytesRemaining() {
         return this.fileRecord.fileSize - this.totalPosition;
     }
-    // Read the entire file (for compatibility with existing getFile API)
+    /**
+     * Read the whole file from the start.
+     *
+     * @returns The bytes, or null when a chunk is missing everywhere or fails its hash check.
+     */
     async readAll() {
         await this.seek(0); // Start from beginning
         const chunks = [];
@@ -199,7 +215,6 @@ class FileReadStream {
         }
         catch (error) {
             // Only return null for chunk-specific errors (not found, download failed)
-            // Rethrow other errors like index file issues
             if (error instanceof Error &&
                 error.message.includes("Chunk") &&
                 (error.message.includes("not found") || error.message.includes("integrity check failed"))) {

package/dist/data/files/file-rows.d.ts

@@ -0,0 +1,77 @@
+import { type IFile } from "./file.types";
+/** What a file's id is derived from. */
+export interface IFileIdentity {
+    fileHash: string;
+    fileSize: number;
+    name: string;
+    /** Empty when unknown; omitted counts as empty. */
+    mimeType?: string;
+    keep: boolean;
+}
+/**
+ * The id of a file: derived from its hash, size, name, MIME type and `keep`, so saving the same
+ * content with the same description gives the same file on every device. Give the name and MIME
+ * type as storage keeps them (`FileWriteStream` normalizes them), or other devices, which
+ * rederive the id from the stored row, refuse it.
+ *
+ * @param file - The file's hash, size, name, MIME type and `keep`.
+ */
+export declare function fileIdFor(file: IFileIdentity): string;
+/**
+ * Whether a row is a legacy file: one saved under a random id, before ids were derived from
+ * content. Legacy rows are admitted as they are, never change, and are always kept.
+ *
+ * @param fileId - The row's id.
+ */
+export declare function isLegacyFileId(fileId: string): boolean;
+/**
+ * Whether a legacy row is a package bundle the installer saved. The runtime owns these, so they
+ * are collected once nothing references them, and their rows may be deleted.
+ *
+ * @param file - The row's id and name.
+ */
+export declare function isLegacyBundleFile(file: Pick<IFile, "fileId" | "name">): boolean;
+/**
+ * Whether this is a runtime-owned package bundle: a legacy bundle, or a derived file with
+ * an installer bundle name, JavaScript MIME type and keep=false. Read keep through its
+ * identity when an older device relayed the row without that column.
+ */
+export declare function isRuntimeBundleFile(file: IFile): boolean;
+/**
+ * Whether a file is kept: never collected, even with nothing referencing it. A legacy row always
+ * is. A row relayed by a build that predates `keep` arrives without it; its id, derived from
+ * `keep`, then decides, and a row whose id says neither is kept.
+ *
+ * @param file - The row.
+ */
+export declare function isKeptFile(file: IFile): boolean;
+/** Whether an unreferenced file may expire, including the runtime's bundle exception. */
+export declare function isCollectableFile(file: IFile): boolean;
+/**
+ * Whether two rows describe the same file, ignoring how an older build stored it (no `keep`, no
+ * MIME type).
+ *
+ * @param a - One row.
+ * @param b - The other.
+ */
+export declare function isSameFile(a: IFile, b: IFile): boolean;
+/**
+ * Why `file` can't be stored as a new row under `recordId`, or undefined when it can. A legacy
+ * row needs only a size within the limit. Any other must have its derived id, a chunk list of
+ * well-formed hashes, one per started MiB, and the `fileHash` of that list.
+ *
+ * @param file - The candidate row.
+ * @param recordId - The record id it's written under.
+ */
+export declare function fileRowProblem(file: IFile, recordId: string): string | undefined;
+/**
+ * The `Files` write check: a new row must pass {@link fileRowProblem}; a stored row never
+ * changes (rewriting the same file is allowed); and only a stored runtime bundle row may be
+ * deleted. Unknown legacy ids remain allowed.
+ *
+ * @param existing - The row as stored, if any.
+ * @param candidate - The row to store, or undefined for a delete.
+ * @param recordId - The record written.
+ * @throws A {@link writeNotAuthorized} refusal.
+ */
+export declare function checkFileWrite(existing: IFile | undefined, candidate: IFile | undefined, recordId: string): void;