@zakkster/lite-bake-stream 1.1.0 → 1.3.0

package/src/Writer.js

@@ -26,10 +26,31 @@
 //   W_MIXED_LANE_TYPES         - a field saw both number and string values
 //   W_LANE_MISMATCH            - post-freeze: value type doesn't match schema lane
 //   W_UNKNOWN_LANE_KIND        - explicit schema declares an unknown laneKind
+//   W_DUPLICATE_FIELD          - schema declares the same field name twice
+//   W_SCHEMA_TOO_WIDE          - a field offset exceeds the u16 offset_in_row ceiling
+//   W_FIELD_NAME_INVALID       - field name empty, non-string, or > 255 UTF-8 bytes
+//   W_FINALIZED                - a sink event or finalize() after finalize()
+//   E_UNKNOWN_OPTION           - unknown constructor option key
+//   E_OPTION_VALUE             - constructor option value out of domain
 
 import { StringTable } from './StringTable.js';
-
-export const VERSION = '1.1.0';
+import { checkOpts } from './Opts.js';
+
+export const VERSION = '1.3.0';
+
+const U32_MAX = 4294967295;
+// Post-finalize sentinel for _recordDepth. Chosen = 2 so every post-finalize
+// sink event lands in an existing cold arm (onNumber/onString depth != 1,
+// onStartObject depth > 1) without adding a per-record compare on the hot path.
+// It is NOT a real nesting depth: onEndObject is unreachable post-finalize
+// because onStartObject throws W_FINALIZED first.
+const FINALIZED_DEPTH = 2;
+const WRITER_OPTS = {
+  schema: { t: 'obj', nullable: true },
+  targetShardBytes: { t: 'int', min: 1, max: U32_MAX },
+  sampleBytes: { t: 'int', min: 0, max: U32_MAX },
+};
+function raiseWriter(code, msg) { throw new WriterError(code, msg); }
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -43,6 +64,11 @@ const FIELD_FLAGS_NONE = 0;
 const SHARD_MIN_READER_VERSION = 1;
 const SHARD_FLAGS_NONE = 0;
 
+// Shared empty view for F64-only shards, which emit NO local string table
+// (SPEC 3.4: local_string_off/local_string_len are 0 when a shard has no
+// U32-lane fields). Read-only; never written into.
+const EMPTY_STRING_TABLE_BYTES = new Uint8Array(0);
+
 const FORMAT_VERSION = 1;
 const ENDIAN_LE = 1;
 
@@ -157,10 +183,11 @@ class SampleBuffer {
 
 export class Writer {
   constructor(opts) {
+    checkOpts('Writer', opts, WRITER_OPTS, raiseWriter);
     opts = opts || {};
-    this._targetShardBytes = opts.targetShardBytes || DEFAULT_SHARD_BYTES;
-    this._sampleBytes = opts.sampleBytes || this._targetShardBytes;
-    this._explicitSchema = opts.schema || null;
+    this._targetShardBytes = opts.targetShardBytes !== undefined ? opts.targetShardBytes : DEFAULT_SHARD_BYTES;
+    this._sampleBytes = opts.sampleBytes !== undefined ? opts.sampleBytes : this._targetShardBytes;
+    this._explicitSchema = opts.schema !== undefined ? opts.schema : null;
 
     // Frozen schema state
     this._schema = null;                // { fields: [{name, laneKind, offsetInRow}], rowStride }
@@ -201,7 +228,10 @@ export class Writer {
 
   onStartObject() {
     this._recordDepth++;
-    if (this._recordDepth > 1) throw new WriterError('W_NESTED_UNSUPPORTED', 'nested object inside record');
+    if (this._recordDepth > 1) {
+      if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+      throw new WriterError('W_NESTED_UNSUPPORTED', 'nested object inside record');
+    }
     if (this._schema) {
       // clear scratch slots
       const f = this._rowValueSlotsF64, u = this._rowValueSlotsU32;
@@ -216,7 +246,8 @@ export class Writer {
   }
 
   onStartArray() {
-    if (this._recordDepth === 0) throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level array (in-record) not supported');
+    if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+    if (this._recordDepth === 0) throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level array is not an object; LBK1 schema mode stores objects only (SPEC 5.1)');
     throw new WriterError('W_NESTED_UNSUPPORTED', 'nested array inside record');
   }
 
@@ -236,7 +267,10 @@ export class Writer {
   }
 
   onNumber(v) {
-    if (this._recordDepth !== 1) return;
+    if (this._recordDepth !== 1) {
+      if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+      throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level number is not an object; LBK1 schema mode stores objects only (SPEC 5.1)');
+    }
     if (this._schema) {
       const idx = this._currentFieldIdx;
       if (idx < 0) return;
@@ -255,7 +289,10 @@ export class Writer {
   onNull()  { this.onNumber(0); }
 
   onString(bytes, from, to) {
-    if (this._recordDepth === 0) return;
+    if (this._recordDepth !== 1) {
+      if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+      throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level string is not an object; LBK1 schema mode stores objects only (SPEC 5.1)');
+    }
     if (this._schema) {
       const idx = this._currentFieldIdx;
       if (idx < 0) return;
@@ -327,14 +364,45 @@ export class Writer {
 
   _finalizeSchema(fields, rowStride) {
     this._schema = { fields, rowStride };
+    // BS-15: a shard with no U32-lane field emits NO local string table.
+    // Computed once at freeze, consulted per shard at finalize / assembly.
+    this._hasU32 = false;
+    for (let i = 0; i < fields.length; i++) {
+      if (fields[i].laneKind === LANE_U32) { this._hasU32 = true; break; }
+    }
 
     const enc = new TextEncoder();
     this._fieldNamesUtf8 = new Array(fields.length);
     this._fieldNameHashes = new Uint32Array(fields.length);
     this._fieldLaneKinds = new Uint8Array(fields.length);
     this._fieldOffsets = new Uint16Array(fields.length);
+    // Freeze-time schema validation (BS-02/BS-03): runs once per schema on both
+    // freeze paths (explicit + sample-drain funnel here), never per record.
+    const seenNames = new Map();
     for (let i = 0; i < fields.length; i++) {
-      const b = enc.encode(fields[i].name);
+      const name = fields[i].name;
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new WriterError('W_FIELD_NAME_INVALID',
+          'field name at index ' + i + ' must be a non-empty string of at most 255 UTF-8 bytes; got ' +
+          (typeof name === 'string' ? '0 bytes' : typeof name));
+      }
+      const b = enc.encode(name);
+      if (b.length > 255) {
+        throw new WriterError('W_FIELD_NAME_INVALID',
+          'field name at index ' + i + ' must be a non-empty string of at most 255 UTF-8 bytes; got ' +
+          b.length + ' bytes');
+      }
+      const first = seenNames.get(name);
+      if (first !== undefined) {
+        throw new WriterError('W_DUPLICATE_FIELD',
+          "duplicate field name '" + name + "' at index " + i + ' (first declared at index ' + first + ')');
+      }
+      seenNames.set(name, i);
+      if (fields[i].offsetInRow > 65535) {
+        throw new WriterError('W_SCHEMA_TOO_WIDE',
+          "field '" + name + "' at offset " + fields[i].offsetInRow +
+          ' exceeds the u16 offset_in_row ceiling (max 65535)');
+      }
       this._fieldNamesUtf8[i] = b;
       this._fieldNameHashes[i] = hashBytes(b, 0, b.length);
       this._fieldLaneKinds[i] = fields[i].laneKind;
@@ -435,9 +503,11 @@ export class Writer {
     const usedBytes = this._currentShardRowCount * this._schema.rowStride;
     const copy = new Uint8Array(usedBytes);
     copy.set(this._currentShardBytes.subarray(0, usedBytes));
-    // Serialize the current shard's string table (empty for F64-only shards).
+    // Serialize the current shard's string table. A shard whose schema has no
+    // U32 lane emits NO table at all (BS-15 / SPEC 3.4): zero bytes here means
+    // the ShardEntry carries local_string_off = 0 / local_string_len = 0.
     const st = this._perShardStringTable || this._stringTable;
-    const stSer = st.serialize();
+    const stBytes = this._hasU32 ? st.serialize().bytes : EMPTY_STRING_TABLE_BYTES;
     // Snapshot zone-map bounds for this shard. Copy so subsequent shards can
     // reuse _currentShardMins/Maxes without clobbering the pushed record.
     const T = this._trackedFieldIndices.length;
@@ -448,7 +518,7 @@ export class Writer {
     this._shards.push({
       bytes: copy,
       rowCount: this._currentShardRowCount,
-      stringTableBytes: stSer.bytes,
+      stringTableBytes: stBytes,
       mins: shardMins,
       maxes: shardMaxes,
     });
@@ -526,7 +596,7 @@ export class Writer {
   }
 
   finalize() {
-    if (this._finalized) return this._container;
+    if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
     if (!this._schema) {
       if (this._sample.rowCount === 0) throw new WriterError('W_EMPTY_INPUT', 'no records to write');
       this._freezeSchemaFromSample();
@@ -536,6 +606,8 @@ export class Writer {
     if (this._shards.length === 0) throw new WriterError('W_EMPTY_INPUT', 'no records to write');
     this._container = this._assembleContainer();
     this._finalized = true;
+    // Post-finalize sentinel: route every later sink event into a cold arm.
+    this._recordDepth = FINALIZED_DEPTH;
     return this._container;
   }
 
@@ -662,7 +734,7 @@ export class Writer {
       dv.setUint16(entryOff + 16, SHARD_MIN_READER_VERSION, true);
       dv.setUint16(entryOff + 18, SHARD_FLAGS_NONE, true);
       dv.setUint32(entryOff + 20, 0, true);   // reserved
-      dv.setBigUint64(entryOff + 24, BigInt(shardStringTableOffsets[i]), true);
+      dv.setBigUint64(entryOff + 24, BigInt(shardStringTableLens[i] > 0 ? shardStringTableOffsets[i] : 0), true);
       dv.setBigUint64(entryOff + 32, BigInt(shardStringTableLens[i]), true);
     }
 

package/src/index.js

@@ -16,6 +16,8 @@ import { StringTable } from './StringTable.js';
 import { PreserveTokenizer, PreserveTokenizerError } from './PreserveTokenizer.js';
 import { PreserveWriter, PreserveWriterError } from './PreserveWriter.js';
 import { PreserveReader, PreserveReaderError } from './PreserveReader.js';
+import { checkOpts } from './Opts.js';
+import { toContainerBuffer } from './Views.js';
 
 export {
   Tokenizer, TokenizerError,
@@ -26,10 +28,17 @@ export {
   PreserveWriter, PreserveWriterError,
   PreserveReader, PreserveReaderError,
 };
-export const VERSION = '1.1.0';
+export const VERSION = '1.3.0';
 
 const encoder = new TextEncoder();
 
+const SERIALIZE_OPTS = {
+  preserve: { t: 'bool' },
+  framing: { t: 'enum', values: ['auto', 'array', 'ndjson'] },
+  writer: { t: 'obj' },
+};
+function raiseSerialize(code, msg) { throw new WriterError(code, msg); }
+
 // Serialize input data into an LBK1 container. Input may be:
 //   - Uint8Array         (raw NDJSON bytes)
 //   - string             (NDJSON text)
@@ -43,22 +52,32 @@ const encoder = new TextEncoder();
 //   writer:    writer options. Schema mode: { schema, targetShardBytes, sampleBytes }.
 //              Preserve mode: { targetShardBytes, maxRecordBytes }.
 export function serialize(input, opts) {
+  // Validate synchronously in the prologue so a typo throws before any async
+  // dispatch (R7): E_UNKNOWN_OPTION must surface as a throw, never a rejected
+  // promise, for ReadableStream / AsyncIterable inputs too.
+  checkOpts('serialize', opts, SERIALIZE_OPTS, raiseSerialize);
   opts = opts || {};
   const preserve = opts.preserve === true;
+  const framing = opts.framing !== undefined ? opts.framing : 'ndjson';
+  const writerOpts = opts.writer !== undefined ? opts.writer : {};
+  if (preserve && opts.framing !== undefined && opts.framing !== 'ndjson') {
+    throw new WriterError('E_OPTION_CONFLICT',
+      "serialize: preserve mode is NDJSON-only; remove framing:'" + opts.framing + "' or set preserve:false");
+  }
 
   if (input && typeof input.getReader === 'function') {
     return preserve
       ? _serializeReadableStreamPreserve(input, opts)
-      : _serializeReadableStream(input, opts.writer || {}, opts.framing || 'ndjson');
+      : _serializeReadableStream(input, writerOpts, framing);
   }
   if (input && typeof input[Symbol.asyncIterator] === 'function') {
     return preserve
       ? _serializeAsyncIterablePreserve(input, opts)
-      : _serializeAsyncIterable(input, opts.writer || {}, opts.framing || 'ndjson');
+      : _serializeAsyncIterable(input, writerOpts, framing);
   }
 
   if (preserve) return _serializeSyncPreserve(input, opts);
-  return _serializeSyncSchema(input, opts.writer || {}, opts.framing || 'ndjson');
+  return _serializeSyncSchema(input, writerOpts, framing);
 }
 
 function _serializeSyncSchema(input, writerOpts, framing) {
@@ -83,10 +102,10 @@ function _serializeSyncSchema(input, writerOpts, framing) {
 }
 
 function _serializeSyncPreserve(input, opts) {
-  const w = new PreserveWriter(opts.writer || {});
+  const w = new PreserveWriter(opts.writer !== undefined ? opts.writer : {});
   const t = new PreserveTokenizer(w, {
     framing: 'ndjson',
-    maxRecordBytes: (opts.writer && opts.writer.maxRecordBytes) || 0,
+    maxRecordBytes: (opts.writer !== undefined && opts.writer.maxRecordBytes !== undefined) ? opts.writer.maxRecordBytes : 0,
   });
   if (input instanceof Uint8Array) {
     t.feed(input);
@@ -124,10 +143,10 @@ async function _serializeReadableStream(stream, writerOpts, framing) {
 }
 
 async function _serializeReadableStreamPreserve(stream, opts) {
-  const w = new PreserveWriter(opts.writer || {});
+  const w = new PreserveWriter(opts.writer !== undefined ? opts.writer : {});
   const t = new PreserveTokenizer(w, {
     framing: 'ndjson',
-    maxRecordBytes: (opts.writer && opts.writer.maxRecordBytes) || 0,
+    maxRecordBytes: (opts.writer !== undefined && opts.writer.maxRecordBytes !== undefined) ? opts.writer.maxRecordBytes : 0,
   });
   const reader = stream.getReader();
   try {
@@ -154,10 +173,10 @@ async function _serializeAsyncIterable(iterable, writerOpts, framing) {
 }
 
 async function _serializeAsyncIterablePreserve(iterable, opts) {
-  const w = new PreserveWriter(opts.writer || {});
+  const w = new PreserveWriter(opts.writer !== undefined ? opts.writer : {});
   const t = new PreserveTokenizer(w, {
     framing: 'ndjson',
-    maxRecordBytes: (opts.writer && opts.writer.maxRecordBytes) || 0,
+    maxRecordBytes: (opts.writer !== undefined && opts.writer.maxRecordBytes !== undefined) ? opts.writer.maxRecordBytes : 0,
   });
   for await (const chunk of iterable) {
     if (!(chunk instanceof Uint8Array)) throw new TypeError('serialize: async iterable must yield Uint8Array');
@@ -170,20 +189,7 @@ async function _serializeAsyncIterablePreserve(iterable, opts) {
 // Deserialize LBK1 bytes into the right Reader for the container's mode.
 // Auto-detects preserve vs schema via header flag byte at offset 7 bit 0.
 export function deserialize(bytes) {
-  let buffer;
-  if (bytes instanceof ArrayBuffer) {
-    buffer = bytes;
-  } else if (bytes instanceof Uint8Array) {
-    if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
-      buffer = bytes.buffer;
-    } else {
-      const copy = new Uint8Array(bytes.byteLength);
-      copy.set(bytes);
-      buffer = copy.buffer;
-    }
-  } else {
-    throw new TypeError('deserialize: expected Uint8Array or ArrayBuffer, got ' + typeof bytes);
-  }
+  const buffer = toContainerBuffer(bytes, 'deserialize');
   if (buffer.byteLength < 8) {
     throw new ReaderError('R_TRUNCATED', 'container too small to inspect header flags');
   }