@zakkster/lite-bake-stream 1.0.0

package/types/Writer.d.ts

@@ -0,0 +1,92 @@
+// Type declarations for @zakkster/lite-bake-stream/writer
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+
+export const VERSION: string;
+
+export type LaneKindName = 'f64' | 'u32';
+export type LaneKindNumeric = 1 | 3;   // 1 = F64, 3 = U32
+
+export interface FieldDeclaration {
+  name: string;
+  /** 'f64' | 'u32' | 1 | 3. */
+  laneKind?: LaneKindName | LaneKindNumeric;
+}
+
+export interface Schema {
+  /** Field names (all F64) or field declarations (mixed lanes). */
+  fields: (string | FieldDeclaration)[];
+}
+
+export interface WriterOptions {
+  schema?: Schema;
+  /** Target output bytes per shard. Default 32 MB. */
+  targetShardBytes?: number;
+  /**
+   * Bytes of input to observe before freezing an inferred schema. Only used
+   * in sample-and-infer mode (no explicit schema). Default = targetShardBytes.
+   */
+  sampleBytes?: number;
+}
+
+export interface FrozenField {
+  name: string;
+  /** 1 = F64, 3 = U32. */
+  laneKind: LaneKindNumeric;
+  offsetInRow: number;
+}
+
+export interface FrozenSchema {
+  fields: FrozenField[];
+  rowStride: number;
+}
+
+export interface Container {
+  buffer: ArrayBuffer;
+  totalRows: number;
+  shardCount: number;
+  schema: FrozenSchema;
+}
+
+export class Writer implements TokenizerSinkForWriter {
+  constructor(opts?: WriterOptions);
+  /**
+   * Sink protocol — the Tokenizer calls these. Byte ranges are ephemeral.
+   */
+  onStartObject(): void;
+  onEndObject(): void;
+  onStartArray(): void;
+  onEndArray(): void;
+  onKey(bytes: Uint8Array, from: number, to: number): void;
+  onNumber(value: number): void;
+  onString(bytes: Uint8Array, from: number, to: number): void;
+  onTrue(): void;
+  onFalse(): void;
+  onNull(): void;
+  onEnd(): void;
+  /** Optional: set the current input byte offset for byte-estimate tracking. */
+  setInputByteOffset(n: number): void;
+  /**
+   * Seal the container and return the LBK1 binary. Call once, after the
+   * Tokenizer has been given `end()`.
+   */
+  finalize(): Container;
+  readonly schema: FrozenSchema | null;
+  readonly totalRows: number;
+  readonly shardCount: number;
+}
+
+// Structural type — the Writer conforms to the Tokenizer's sink protocol.
+// (Redeclared here so the /writer subpath is self-contained.)
+interface TokenizerSinkForWriter {
+  onStartObject(): void;
+  onEndObject(): void;
+  onKey(bytes: Uint8Array, from: number, to: number): void;
+  onNumber(value: number): void;
+  onString(bytes: Uint8Array, from: number, to: number): void;
+}
+
+export class WriterError extends Error {
+  code: string;
+  name: 'WriterError';
+  constructor(code: string, message: string);
+}

package/types/index.d.ts

@@ -0,0 +1,58 @@
+// Type declarations for @zakkster/lite-bake-stream (root entry)
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+
+export { Tokenizer, TokenizerError } from './Tokenizer.d.ts';
+export type { TokenizerSink, TokenizerOptions } from './Tokenizer.d.ts';
+export { Writer, WriterError } from './Writer.d.ts';
+export type {
+  Schema, FieldDeclaration, WriterOptions,
+  FrozenField, FrozenSchema, Container,
+  LaneKindName, LaneKindNumeric,
+} from './Writer.d.ts';
+export { Reader, ReaderError } from './Reader.d.ts';
+export type {
+  ShardHandle, StringTableView, Bounds, FindShardsOptions,
+} from './Reader.d.ts';
+export { StringTable } from './StringTable.d.ts';
+export { PreserveTokenizer, PreserveTokenizerError } from './PreserveTokenizer.d.ts';
+export type { PreserveSink, PreserveTokenizerOptions } from './PreserveTokenizer.d.ts';
+export { PreserveWriter, PreserveWriterError } from './PreserveWriter.d.ts';
+export type { PreserveWriterOptions, PreserveContainer } from './PreserveWriter.d.ts';
+export { PreserveReader, PreserveReaderError } from './PreserveReader.d.ts';
+export type { PreserveShardHandle } from './PreserveReader.d.ts';
+
+export const VERSION: string;
+
+export interface SerializeOptions {
+  /** When true, use preserve mode: opaque byte blobs, any JSON shape. */
+  preserve?: boolean;
+  framing?: 'ndjson' | 'array' | 'auto';
+  /**
+   * Writer options. Union of schema-mode and preserve-mode fields.
+   * Schema mode reads schema/targetShardBytes/sampleBytes.
+   * Preserve mode reads targetShardBytes/maxRecordBytes.
+   */
+  writer?: import('./Writer.d.ts').WriterOptions & import('./PreserveWriter.d.ts').PreserveWriterOptions;
+}
+
+/**
+ * One-shot compile input data to an LBK1 container.
+ * Schema mode (default): F64/U32 lane packing, query pruning.
+ * Preserve mode (opts.preserve=true): opaque byte blobs, any JSON shape.
+ */
+export function serialize(
+  input: Uint8Array | string | Iterable<object>,
+  opts?: SerializeOptions
+): Uint8Array;
+export function serialize(
+  input: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
+  opts?: SerializeOptions
+): Promise<Uint8Array>;
+
+/**
+ * Deserialize LBK1 bytes into the right Reader for the container's mode.
+ * Auto-detects preserve vs schema via the header flag byte.
+ */
+export function deserialize(
+  bytes: Uint8Array | ArrayBuffer
+): import('./Reader.d.ts').Reader | import('./PreserveReader.d.ts').PreserveReader;