@elaraai/east 1.0.44 → 1.0.46

package/dist/src/serialization/beast2/index.d.ts

@@ -3,15 +3,12 @@
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
 /**
- * Beast2 v2 — complete encoder and decoder.
+ * Beast2 container — version-agnostic public entry points.
  *
- * File layout: magic(8) + type_table_section + string_table_section + value_data
- * Type table: flat array of unique types, referenced by varint index.
- * String table: flat array of unique strings, referenced by varint index.
- * Value data: type-driven positional encoding, no inline type tags.
- * Functions: IR encoded directly — EastTypeType schema positions auto-emit type table indices.
- *
- * See devdocs/BEAST2.md for the full specification.
+ * Decoders dispatch on the magic's version byte (`v4` = 0x04, `v5` = 0x05) so
+ * every entry point accepts blobs of either container version. Encoders write
+ * the v4 container by default. See `SPEC.md` for the magic registry and
+ * version policy, `v4/SPEC.md` and `v5/SPEC.md` for the wire formats.
  */
 import { type EastTypeValue } from "../../type_of_type.js";
 import type { EastType, ValueTypeOf } from "../../types.js";
@@ -19,32 +16,89 @@ import { type FunctionIR, type AsyncFunctionIR } from "../../ir.js";
 import type { PlatformFunction } from "../../platform.js";
 import { EastIR, AsyncEastIR } from "../../eastir.js";
 import type { SourceMap } from "../../location.js";
-export declare const MAGIC_BYTES: Uint8Array<ArrayBuffer>;
-export type Beast2DecodeOptions = {
-    platform?: PlatformFunction[];
-};
-export declare function encodeBeast2For(type: EastTypeValue, options?: {
+import { type Beast2DecodeOptions } from "./shared.js";
+import type { Beast2Codec } from "./v5/frames.js";
+import { type Beast2Version } from "./version.js";
+export { MAGIC_BYTES } from "./v4/container.js";
+export { MAGIC_BYTES_V5 } from "./v5/codec.js";
+export type { Beast2DecodeOptions } from "./shared.js";
+export type { Beast2Codec } from "./v5/frames.js";
+export { Beast2Writer, type Beast2WriterOptions, encodeBeast2SegmentsFor, iterBeast2SegmentsFor, Beast2Pages, openBeast2PagesFor, } from "./v5/stream.js";
+export { BEAST2_WRITE_VERSION, BEAST2_READ_VERSIONS, type Beast2Version } from "./version.js";
+/** Options accepted by {@link encodeBeast2For}. */
+export type Beast2EncodeOptions = {
+    /** Explicit source map to embed (overrides discovery from function values). */
     sourceMap?: SourceMap | null;
-}): (value: any) => Uint8Array;
-export declare function encodeBeast2For<T extends EastType>(type: T, options?: {
-    sourceMap?: SourceMap | null;
-}): (value: ValueTypeOf<T>) => Uint8Array;
+    /** Container version to write. Defaults to `5`. Pass `4` to write the
+     *  legacy globally-sectioned container for a reader that predates v5. */
+    version?: Beast2Version;
+    /** v5 only: per-frame codec. Defaults to `"deflate"`. */
+    codec?: Beast2Codec;
+    /** v5 only: write the trailing index + footer (container roots).
+     *  Defaults to `false`. */
+    index?: boolean;
+};
+/**
+ * Builds an encoder closure for the given type.
+ *
+ * The returned function encodes values of `type` into a self-contained beast2
+ * blob. The container version defaults to v5 — the segment-terminated record
+ * stream (see `v5/SPEC.md`), deflate-framed — and accepts the `codec` and
+ * `index` options. Pass `version: 4` for the legacy container; decode entry
+ * points accept every version regardless.
+ *
+ * @param type - the root East type (as `EastType` or `EastTypeValue`)
+ * @param options - encode options (source map, container version, v5 codec/index)
+ * @returns a reusable function encoding values of `type` to beast2 bytes
+ */
+export declare function encodeBeast2For(type: EastTypeValue, options?: Beast2EncodeOptions): (value: any) => Uint8Array;
+export declare function encodeBeast2For<T extends EastType>(type: T, options?: Beast2EncodeOptions): (value: ValueTypeOf<T>) => Uint8Array;
+/**
+ * Builds a decoder closure for the given type.
+ *
+ * The returned function dispatches on the blob's magic version byte, so v4
+ * blobs decode through the same entry point as newer container versions.
+ *
+ * @param type - the expected root East type (as `EastType` or `EastTypeValue`)
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns a reusable function decoding beast2 bytes to values of `type`
+ */
 export declare function decodeBeast2For(type: EastTypeValue, options?: Beast2DecodeOptions): (data: Uint8Array) => any;
 export declare function decodeBeast2For<T extends EastType>(type: T, options?: Beast2DecodeOptions): (data: Uint8Array) => ValueTypeOf<T>;
+/**
+ * Builds an async decoder closure for the given type.
+ *
+ * Identical to {@link decodeBeast2For} but decompresses v5 deflate frames with
+ * the platform's async decompressor (`DecompressionStream`), so it works in
+ * browsers where Node's zlib is unavailable. v4 blobs decode synchronously.
+ *
+ * @param type - the expected root East type (as `EastType` or `EastTypeValue`)
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns a reusable async function decoding beast2 bytes to values of `type`
+ */
+export declare function decodeBeast2ForAsync(type: EastTypeValue, options?: Beast2DecodeOptions): (data: Uint8Array) => Promise<any>;
+export declare function decodeBeast2ForAsync<T extends EastType>(type: T, options?: Beast2DecodeOptions): (data: Uint8Array) => Promise<ValueTypeOf<T>>;
+/**
+ * Decodes a self-describing blob using its embedded root type.
+ *
+ * @param data - a beast2 blob of any supported container version
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns the blob's root type and decoded value
+ */
+export declare function decodeBeast2(data: Uint8Array, options?: Beast2DecodeOptions): {
+    type: EastTypeValue;
+    value: any;
+};
 /** Encode an EastIR (or AsyncEastIR) as a beast2 blob that carries both the
  *  IR and its source map. Prefer this over `encodeBeast2For(IRType)(ir)` when
  *  encoding a program rather than opaque IR data. */
-export declare function encodeEastIR<I extends any[], O>(eastIR: EastIR<I, O> | AsyncEastIR<I, O>): Uint8Array;
+export declare function encodeEastIR<I extends any[], O>(eastIR: EastIR<I, O> | AsyncEastIR<I, O>, options?: Omit<Beast2EncodeOptions, "sourceMap">): Uint8Array;
 /** Decode a beast2 blob whose root is a Function IR into an EastIR. The
  *  returned wrapper has its source_map populated from the blob's source_map
  *  section, so downstream compile() resolves loc_ids automatically. */
 export declare function decodeEastIR<I extends any[] = any[], O = any>(data: Uint8Array): EastIR<I, O>;
 /** Async-function variant of decodeEastIR. */
 export declare function decodeAsyncEastIR<I extends any[] = any[], O = any>(data: Uint8Array): AsyncEastIR<I, O>;
-export declare function decodeBeast2(data: Uint8Array, options?: Beast2DecodeOptions): {
-    type: EastTypeValue;
-    value: any;
-};
 export declare function compileFunctionIR<I extends any[], O>(ir: FunctionIR, platform: PlatformFunction[]): (...args: I) => O;
 export declare function compileAsyncFunctionIR<I extends any[], O>(ir: AsyncFunctionIR, platform: PlatformFunction[]): (...args: I) => Promise<O>;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/serialization/beast2/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/serialization/beast2/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAO5D,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAItD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAmDnD,eAAO,MAAM,WAAW,yBAAmE,CAAC;AAkB5F,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC/B,CAAC;AAglBF,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,UAAU,CAAA;AAC5H,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,UAAU,CAAA;AAqE/I,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,GAAG,CAAA;AAC9G,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,WAAW,CAAC,CAAC,CAAC,CAAA;AAgDjI;;qDAEqD;AACrD,wBAAgB,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAErG;AAED;;uEAEuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAQ7F;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAQvG;AAkCD,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,CA2BjH;AAQD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAErH;AAED,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAExI"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/serialization/beast2/index.ts"],"names":[],"mappings":"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"}