@hashtree/core 0.1.0

package/dist/hashtree.d.ts

@@ -0,0 +1,237 @@
+/**
+ * HashTree - Unified merkle tree operations
+ *
+ * Single class for creating, reading, and editing content-addressed merkle trees.
+ *
+ * All files are encrypted by default using CHK (Content Hash Key) encryption.
+ * Use the "Public" variants (putFilePublic, readFilePublic) for unencrypted storage.
+ */
+import { Store, Hash, CID, TreeNode, LinkType } from './types.js';
+import { StreamWriter } from './streaming.js';
+import * as streaming from './streaming.js';
+export { StreamWriter } from './streaming.js';
+export { verifyTree } from './verify.js';
+/** Default chunk size: 2MB (optimized for blossom uploads) */
+export declare const DEFAULT_CHUNK_SIZE: number;
+export interface HashTreeConfig {
+    store: Store;
+    chunkSize?: number;
+}
+export interface TreeEntry {
+    name: string;
+    cid: CID;
+    size: number;
+    type: LinkType;
+    meta?: Record<string, unknown>;
+}
+export interface DirEntry {
+    name: string;
+    cid: CID;
+    size: number;
+    type: LinkType;
+    meta?: Record<string, unknown>;
+}
+/**
+ * HashTree - create, read, and edit merkle trees
+ */
+export declare class HashTree {
+    private store;
+    private chunkSize;
+    constructor(config: HashTreeConfig);
+    private get config();
+    putBlob(data: Uint8Array): Promise<Hash>;
+    /**
+     * Store a file
+     * @param data - File data to store
+     * @param options - { unencrypted?: boolean } - if true, store without encryption
+     * @returns { cid, size }
+     */
+    putFile(data: Uint8Array, options?: {
+        unencrypted?: boolean;
+    }): Promise<{
+        cid: CID;
+        size: number;
+    }>;
+    /**
+     * Store a directory
+     * @param entries - Directory entries
+     * @param options - { unencrypted?: boolean } - if true, store without encryption
+     * @returns { cid, size }
+     */
+    putDirectory(entries: DirEntry[], options?: {
+        unencrypted?: boolean;
+    }): Promise<{
+        cid: CID;
+        size: number;
+    }>;
+    getBlob(hash: Hash): Promise<Uint8Array | null>;
+    /**
+     * Get a tree node
+     */
+    getTreeNode(id: CID): Promise<TreeNode | null>;
+    getType(id: CID): Promise<LinkType>;
+    isDirectory(id: CID): Promise<boolean>;
+    /**
+     * Read a file
+     */
+    readFile(id: CID): Promise<Uint8Array | null>;
+    /**
+     * Stream a file
+     * @param id - CID of the file
+     * @param options - { offset?: number, prefetch?: number }
+     */
+    readFileStream(id: CID, options?: {
+        offset?: number;
+        prefetch?: number;
+    }): AsyncGenerator<Uint8Array>;
+    /**
+     * Read a range of bytes from a file
+     */
+    readFileRange(id: CID, start: number, end?: number): Promise<Uint8Array | null>;
+    /**
+     * List directory entries
+     */
+    listDirectory(id: CID): Promise<TreeEntry[]>;
+    /**
+     * Resolve a path to get the entry's CID
+     *
+     * @param root - Root CID of the tree
+     * @param path - Path to resolve (string like 'a/b/file.txt' or array like ['a', 'b', 'file.txt'])
+     * @returns { cid, type } or null if not found
+     */
+    resolvePath(root: CID, path: string | string[]): Promise<{
+        cid: CID;
+        type: LinkType;
+    } | null>;
+    getSize(hash: Hash): Promise<number>;
+    walk(hash: Hash, path?: string): AsyncGenerator<{
+        path: string;
+        hash: Hash;
+        type: LinkType;
+        size?: number;
+    }>;
+    /**
+     * Walk entire tree and return all entries as an array
+     * More convenient than the async generator for most use cases
+     * @param id - Root CID of the tree
+     * @param options.includeData - If true, include file data in results
+     * @param options.filesOnly - If true, only return files (not directories)
+     */
+    walkTree(id: CID, options?: {
+        includeData?: boolean;
+        filesOnly?: boolean;
+    }): Promise<Array<{
+        path: string;
+        cid: CID;
+        type: LinkType;
+        size: number;
+        data?: Uint8Array;
+    }>>;
+    /**
+     * Iterate over all raw blocks in a merkle tree
+     * Yields each block's hash and data, traversing encrypted nodes correctly
+     * Useful for syncing to remote stores (e.g., Blossom push)
+     */
+    walkBlocks(id: CID): AsyncGenerator<{
+        hash: Hash;
+        data: Uint8Array;
+    }>;
+    /**
+     * Pull (fetch) all chunks for a tree recursively
+     * Triggers WebRTC fetches for any missing chunks
+     * Uses parallel fetching within each tree level for better performance
+     * @returns { cid, chunks, bytes } - The CID and stats about what was pulled
+     */
+    pull(id: CID): Promise<{
+        cid: CID;
+        chunks: number;
+        bytes: number;
+    }>;
+    /**
+     * Push all chunks for a tree to a target store
+     * Useful for syncing to remote stores (e.g., Blossom servers)
+     * @param id - CID of the tree to push
+     * @param targetStore - Store to push blocks to (must support put())
+     * @param options - callbacks for progress and per-block status
+     * @returns { cid, pushed, skipped, failed, bytes, errors } - The CID and detailed stats
+     */
+    push(id: CID, targetStore: Store, options?: {
+        onProgress?: (current: number, total: number) => void;
+        onBlock?: (hash: Hash, status: 'success' | 'skipped' | 'error', error?: Error) => void;
+        /** Number of parallel uploads (default: 4) */
+        concurrency?: number;
+        /** AbortSignal to cancel the push */
+        signal?: AbortSignal;
+    }): Promise<{
+        cid: CID;
+        pushed: number;
+        skipped: number;
+        failed: number;
+        bytes: number;
+        errors: Array<{
+            hash: Hash;
+            error: Error;
+        }>;
+        cancelled: boolean;
+    }>;
+    /**
+     * Add or update an entry in a directory
+     * @param root - Root CID of the tree
+     * @param path - Path to the directory containing the entry
+     * @param name - Name of the entry
+     * @param entry - CID of the entry content
+     * @param size - Size of the content
+     * @param type - Type of the entry (LinkType.Blob, LinkType.File, or LinkType.Dir)
+     * @returns New root CID
+     */
+    setEntry(root: CID, path: string[], name: string, entry: CID, size: number, type?: LinkType, meta?: Record<string, unknown>): Promise<CID>;
+    /**
+     * Remove an entry from a directory
+     * @param root - Root CID of the tree
+     * @param path - Path to the directory containing the entry
+     * @param name - Name of the entry to remove
+     * @returns New root CID
+     */
+    removeEntry(root: CID, path: string[], name: string): Promise<CID>;
+    /**
+     * Rename an entry in a directory
+     * @param root - Root CID of the tree
+     * @param path - Path to the directory containing the entry
+     * @param oldName - Current name
+     * @param newName - New name
+     * @returns New root CID
+     */
+    renameEntry(root: CID, path: string[], oldName: string, newName: string): Promise<CID>;
+    /**
+     * Move an entry to a different directory
+     * @param root - Root CID of the tree
+     * @param sourcePath - Path to the source directory
+     * @param name - Name of the entry to move
+     * @param targetPath - Path to the target directory
+     * @returns New root CID
+     */
+    moveEntry(root: CID, sourcePath: string[], name: string, targetPath: string[]): Promise<CID>;
+    /**
+     * Write data at a specific offset in a file
+     * Only affected chunks are rewritten - efficient for small patches to large files.
+     * Useful for updating file headers (e.g., WebM duration) without rewriting entire file.
+     *
+     * @param fileCid - CID of the file to modify
+     * @param offset - Byte offset to write at
+     * @param data - Data to write
+     * @returns New file CID
+     */
+    writeAt(fileCid: CID, offset: number, data: Uint8Array): Promise<CID>;
+    getStore(): Store;
+    /**
+     * Create a streaming file writer for incremental appends
+     * Useful for writing large files chunk by chunk (e.g., video recording)
+     * @param options.unencrypted - if true, create without encryption
+     * @param options.chunker - custom chunker for variable chunk sizes (e.g., videoChunker for faster start)
+     */
+    createStream(options?: {
+        unencrypted?: boolean;
+        chunker?: streaming.Chunker;
+    }): StreamWriter;
+}
+//# sourceMappingURL=hashtree.d.ts.map

package/dist/hashtree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashtree.d.ts","sourceRoot":"","sources":["../src/hashtree.ts"],"names":[],"mappings":"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"}