file

Purpose

Per-file consistency invariants for every FileTemplate (DTP-09). Files that fail any invariant are rejected with DRIVE.TEMPLATE_MALFORMED and a context object naming the offending file path. The walker recurses through the folder tree so the failure surfaces with the full path from the root.

Features

assertFolderFileInvariants(folder) — recurses, checking every nested file.
assertFile(file, path) — single-file check, used directly in the hydration scheduler when files arrive piecemeal.
MIN_CHUNK_SIZE_EXCLUSIVE constant (164) — the chunk-format header overhead requires at least one payload byte.
Five gates: chunkSize > 164, totalChunks * chunkSize >= size, manifestKey non-empty, checksum matches 'blake3:<hex>' or 'sha256:<hex>', manifestSig non-empty.

Usage: Basic Example

import { assertFile } from "@suaveplan/drive-template";

assertFile(file, "/photos/wedding.jpg");
// throws DriveTemplateError(DRIVE.TEMPLATE_MALFORMED) on any invariant violation

Usage: Advanced Example

import {
    assertFolderFileInvariants,
    DTP_CODES,
    DriveTemplateError,
} from "@suaveplan/drive-template";

function reportFileFailures(folder) {
    try {
        assertFolderFileInvariants(folder);
        return null;
    } catch (err) {
        if (err instanceof DriveTemplateError && err.code === DTP_CODES.TEMPLATE_MALFORMED) {
            const ctx = err.context as { file: string; issue: string };
            return { file: ctx.file, issue: ctx.issue };
        }
        throw err;
    }
}

API Reference

assertFolderFileInvariants(folder: FolderTemplate): void.
assertFile(file: FileTemplate, path: string): void.
MIN_CHUNK_SIZE_EXCLUSIVE: 164 — exclusive lower bound for chunkSize.

Implementation Notes

The 164-byte chunk-format overhead matches @suaveplan/drive-plugin-chunks HEADER_SIZE. Keeping chunkSize strictly greater than the header ensures every chunk carries at least one byte of payload — otherwise the manifest would describe a file that consists entirely of headers with no bytes. The checksum regex accepts both blake3:<hex> and sha256:<hex> forms so consumers running on platforms without BLAKE3 native bindings can still ship templates checksummed via SHA-256. Folder traversal accumulates the path through the spread operator, which keeps the failure context's file field human-readable for any UI surfacing the error.

2.4 KiB Raw Blame History