chunk-keys

Purpose

Implements the chunk-keys layout strategy that stores each chunk under a discrete storage key (chunks/<fileIdHex>/<chunkId>). This is the simplest layout — every chunk is a separate set/get operation, no preallocation, no offset arithmetic — and it works on any DriveStorage whose set and list methods are implemented.

Features

createChunkKeysLayout(storage): ChunkLayout — factory returning a ChunkLayout with name: "chunk-keys".
putChunk(fileId, chunkId, rawBytes) — single storage.set call.
getChunk(fileId, chunkId) — single storage.get call returning undefined for missing chunks (no error).
hasChunks(fileId) — returns a sparse boolean[] indexed by chunkId, derived from storage.list({ prefix }).
availableChunks(fileId) — flattens hasChunks into the list of present indices.

Usage: Basic Example

import { Drive } from "@suaveplan/drive";
import { chunksPlugin } from "@suaveplan/drive-plugin-chunks";
import { MemoryStorage } from "@suaveplan/storage/memory";

const storage = Object.assign(new MemoryStorage(), { id: "default" });
const drive = new Drive(storage);
await drive.initialize();

const chunks = await drive.usePlugin(
    chunksPlugin({ serverPrivKey, serverPubKey, layout: "chunk-keys" })
);

Usage: Advanced Example

import { createChunkKeysLayout } from "@suaveplan/drive-plugin-chunks";

const layout = createChunkKeysLayout(storage);
await layout.putChunk(fileId, 0, raw);
const present = await layout.hasChunks(fileId);
const available = await layout.availableChunks(fileId);
console.log(`have ${available.length}/${present.length}`);

API Reference

createChunkKeysLayout(storage: DriveStorage): ChunkLayout.
ChunkLayout.name === "chunk-keys".
putChunk(fileId, chunkId, rawBytes): Promise<void>.
getChunk(fileId, chunkId): Promise<Uint8Array | undefined>.
hasChunks(fileId): Promise<boolean[]> — bits.length === maxChunkId + 1; uses -1 sentinel when no chunks exist (yields empty array).
availableChunks(fileId): Promise<number[]>.

Implementation Notes

The hex helper formats fileId to lowercase hex with leading zeros, identical to the formatting in plugin.ts so stored chunks remain addressable across plugin and layout boundaries. hasChunks uses storage.list({ prefix }) once and then computes the bit array client-side, which is O(n) over present chunks and avoids n storage round trips. Missing chunks correspond to false slots in the bit array; gaps are explicit, not implicit.

2.5 KiB Raw Blame History