yom-format 0.1.0

package/src/yom/zstd.ts

@@ -0,0 +1,47 @@
+import { init, compress, decompress } from "@bokuweb/zstd-wasm";
+import { CorruptBlobError } from "./errors.js";
+
+/**
+ * Thin wrapper over `@bokuweb/zstd-wasm`, the Web analogue of the Swift
+ * implementation in `swift/Sources/YOMFormat/ZstdCodec.swift`'s vendored
+ * libzstd wrapper. Every YOM
+ * blob is bounded and self-describing (zstd frames carry their own content
+ * size), so the one-shot simple API is enough -- no streaming/dictionary
+ * support is needed here either.
+ */
+let initPromise: Promise<void> | null = null;
+
+function ensureInit(): Promise<void> {
+  if (!initPromise) {
+    initPromise = init();
+  }
+  return initPromise;
+}
+
+/** Compression level mirrors `ZstdCodec.compressionLevel` (favor decode speed). */
+const COMPRESSION_LEVEL = 3;
+
+export async function zstdCompress(data: Uint8Array): Promise<Uint8Array> {
+  await ensureInit();
+  return compress(data, COMPRESSION_LEVEL);
+}
+
+/**
+ * Decompresses a zstd frame and asserts the output is exactly `expectedSize`
+ * bytes (the blob's index-declared `uncompressed_length`), converging on the
+ * Swift `ZstdCodec.decompress(_, originalSize:)` discipline.
+ *
+ * `@bokuweb/zstd-wasm`'s `decompress` takes no target-size argument (it sizes
+ * its output buffer from the frame's own declared content size), so the guard
+ * against a size-lying frame is this exact-length check plus the caller's
+ * declared-size cap (`enforceBlobSizePolicy`). A mismatch throws
+ * `CorruptBlobError` before the bytes are used, ahead of the SHA-256 gate.
+ */
+export async function zstdDecompress(data: Uint8Array, expectedSize: number): Promise<Uint8Array> {
+  await ensureInit();
+  const out = decompress(data);
+  if (out.length !== expectedSize) {
+    throw new CorruptBlobError(`zstd output length ${out.length} != declared ${expectedSize}`);
+  }
+  return out;
+}