@reifydb/core 0.9.1 → 0.9.3

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 declare const NONE_VALUE = "\u27EAnone\u27EB";
+declare function noneMarker(depth: number): string;
+declare function noneMarkerDepth(payload: string): number | undefined;
 declare const ROW_NUMBER_KEY = "#rownum";
 
 /**
@@ -709,9 +711,9 @@ declare class Uint16Value implements Value {
 
 declare class NoneValue implements Value {
     readonly type: Type;
-    readonly innerType: BaseType;
-    constructor(innerType?: BaseType);
-    static parse(str: string, innerType?: BaseType): NoneValue;
+    readonly innerType: Type;
+    constructor(innerType?: Type);
+    static parse(str: string, innerType?: Type): NoneValue;
     isNone(): boolean;
     toString(): string;
     valueOf(): undefined;
@@ -721,6 +723,25 @@ declare class NoneValue implements Value {
     toJSON(): null;
     encode(): TypeValuePair;
 }
+declare function noneDepth(v: NoneValue): number;
+
+declare const OPTION_BRAND: unique symbol;
+declare function isOption(value: unknown): value is Option<unknown>;
+declare class Option<T> {
+    private readonly state;
+    readonly [OPTION_BRAND] = true;
+    private constructor();
+    static some<T>(value: T): Option<T>;
+    static none<T = never>(inner: Type): Option<T>;
+    isSome(): boolean;
+    isNone(): boolean;
+    unwrap(): T;
+    unwrapOr(fallback: T): T;
+    map<U>(fn: (value: T) => U): Option<U>;
+    get type(): OptionType;
+    toString(): string;
+    toJSON(): unknown;
+}
 
 declare class Utf8Value implements Value {
     readonly type: Type;
@@ -913,6 +934,45 @@ declare class IdentityIdValue implements Value {
     encode(): TypeValuePair;
 }
 
+/**
+ * The wire rendering of a type: an object whose `id` names it, with anything it wraps under `underlying`.
+ *
+ * The client keeps its own representation, where a base type is the bare string it switches on. These two
+ * functions are the only crossing between the two, so a wire descriptor never reaches code that expects
+ * `{Option: ...}` and a client type never reaches the server expecting `{id, underlying}`.
+ */
+interface WireType {
+    id: string;
+    underlying?: WireType;
+}
+declare function typeToWire(type: Type): WireType;
+declare function typeFromWire(wire: WireType): Type;
+/** Reads the column types of a frames payload, leaving the rest of the frame untouched. */
+declare function columnsFromWire<T extends {
+    type: any;
+}>(columns: T[]): T[];
+declare function framesFromWire(frames: any[]): any[];
+/**
+ * Reads a `format=json` frame envelope into the column shape the decoder works on.
+ *
+ * The rows carry one value per column and the envelope's `types` says what each column is, so the two
+ * together hold everything the frames format carries. Turning them back into columns lets the JSON
+ * transports run the same decode and the same shape check as every other transport, instead of handing
+ * the caller whatever JSON happened to arrive.
+ */
+declare function envelopeToColumns(envelope: any): {
+    name: string;
+    type: Type;
+    payload: string[];
+}[];
+declare function envelopesToFrames(envelopes: any): {
+    columns: {
+        name: string;
+        type: Type;
+        payload: string[];
+    }[];
+}[];
+
 type BaseType = "Blob" | "Boolean" | "Decimal" | "Float4" | "Float8" | "Int1" | "Int2" | "Int4" | "Int8" | "Int16" | "Uint1" | "Uint2" | "Uint4" | "Uint8" | "Uint16" | "Utf8" | "Date" | "DateTime" | "Time" | "Duration" | "Uuid4" | "Uuid7" | "IdentityId" | "None";
 interface OptionType {
     Option: Type;
@@ -920,6 +980,8 @@ interface OptionType {
 type Type = BaseType | OptionType;
 declare function isOptionType(t: Type): t is OptionType;
 declare function unwrapOptionType(t: Type): BaseType;
+declare function optionDepth(t: Type): number;
+declare function innerOfOption(t: OptionType): Type;
 interface TypeValuePair {
     type: Type;
     value: string;
@@ -987,7 +1049,7 @@ type PrimitiveToValue<T extends BaseType> = PrimitiveValueMap[T];
 type CamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
 type InferShape<S> = S extends PrimitiveShapeNode<infer T> ? T extends BaseType ? PrimitiveToTS<T> : never : S extends ValueShapeNode<infer T> ? T extends BaseType ? PrimitiveToValue<T> : never : S extends ObjectShapeNode<infer P> ? {
     [K in keyof P as CamelCase<K & string>]: InferShape<P[K]>;
-} : S extends ArrayShapeNode<infer T> ? InferShape<T>[] : S extends OptionalShapeNode<infer T> ? InferShape<T> | undefined : never;
+} : S extends ArrayShapeNode<infer T> ? InferShape<T>[] : S extends OptionShapeNode<infer T> ? Option<InferShape<T>> : never;
 type InferShapes<S extends readonly ShapeNode[]> = {
     [K in keyof S]: InferShape<S[K]>[];
 };
@@ -1026,7 +1088,7 @@ declare class ShapeBuilder {
     static identityid(): PrimitiveShapeNode<'IdentityId'>;
     static object<P extends Record<string, ShapeNode>>(properties: P): ObjectShapeNode<P>;
     static array<T extends ShapeNode>(items: T): ArrayShapeNode<T>;
-    static optional<T extends ShapeNode>(shape: T): OptionalShapeNode<T>;
+    static option<T extends ShapeNode>(inner: T): OptionShapeNode<T>;
     static number(): PrimitiveShapeNode<'Float8'>;
     static booleanValue(): ValueShapeNode<'Boolean'>;
     static decimalValue(): ValueShapeNode<'Decimal'>;
@@ -1062,6 +1124,12 @@ declare function validateShape(shape: ShapeNode, value: any): boolean;
 declare function transformFrames<const S extends readonly ShapeNode[]>(frames: any[][], shapes: S): FrameResults<S>;
 declare function transformResult(row: any, resultShape: any): any;
 
+declare class ShapeMismatch extends Error {
+    constructor(message: string);
+}
+declare function checkFrames(frames: Frame[], shapes: readonly ShapeNode[]): void;
+declare function checkFrame(columns: Column[], shape: ShapeNode): void;
+
 interface PrimitiveShapeNode<T extends string = string> {
     kind: 'primitive';
     type: T;
@@ -1074,15 +1142,15 @@ interface ArrayShapeNode<T extends ShapeNode = ShapeNode> {
     kind: 'array';
     items: T;
 }
-interface OptionalShapeNode<T extends ShapeNode = ShapeNode> {
-    kind: 'optional';
-    shape: T;
+interface OptionShapeNode<T extends ShapeNode = ShapeNode> {
+    kind: 'option';
+    inner: T;
 }
 interface ValueShapeNode<T extends string = string> {
     kind: 'value';
     type: T;
 }
-type ShapeNode = PrimitiveShapeNode | ObjectShapeNode | ArrayShapeNode | OptionalShapeNode | ValueShapeNode;
+type ShapeNode = PrimitiveShapeNode | ObjectShapeNode | ArrayShapeNode | OptionShapeNode | ValueShapeNode;
 
 type Params = (TypeValuePair | null)[] | Record<string, TypeValuePair | null>;
 interface Frame {
@@ -1149,8 +1217,13 @@ declare function asFrameResults<S extends readonly ShapeNode[]>(results: any): F
 declare function decode(pair: TypeValuePair): Value;
 declare function columnsToRows(columns: Column[]): Record<string, Value>[];
 
-declare function encodeValue(value: any): TypeValuePair;
-declare function encodeParams(params: any): TypeValuePair[] | Record<string, TypeValuePair>;
+declare function encodeValue(value: any, name?: string): TypeValuePair;
+/** A parameter as it goes on the wire: the same value, with the type in the wire's own rendering. */
+interface WireValue {
+    type: WireType;
+    value: string;
+}
+declare function encodeParams(params: any): WireValue[] | Record<string, WireValue>;
 
 declare const TYPE_CODE: {
     readonly None: 0;
@@ -1246,4 +1319,4 @@ interface RqlToken {
 }
 declare function tokenizeRql(source: string): RqlToken[];
 
-export { type ArrayShapeNode, type BaseType, BlobValue, BooleanValue, type Column, type ColumnAlign, DateTimeValue, DateValue, DecimalValue, type Diagnostic, type DiagnosticColumn, DurationValue, type ErrorResponse, Float4Value, Float8Value, type Fragment, type Frame, type FrameResults, IdentityIdValue, type InferShape, type InferShapes, Int16Value, Int1Value, Int2Value, Int4Value, Int8Value, type MissingPresentation, NONE_PRESENTATION, NONE_VALUE, NoneValue, type ObjectShapeNode, type OptionType, type OptionalShapeNode, type Params, type PlannedColumn, type PrimitiveShapeNode, type PrimitiveToTS, type PrimitiveToValue, ROW_NUMBER_KEY, RQL_KEYWORDS, RQL_LITERALS, RQL_OPERATORS, RQL_SYSTEM_COLUMNS, RQL_TYPES, ReifyError, type ResultColumn, type RqlToken, type RqlTokenKind, Shape, ShapeBuilder, type ShapeNode, type SingleFrameResult, TYPE_CODE, type TableLayoutOptions, type TablePlan, TimeValue, type Type, type TypeName, type TypeValuePair, Uint16Value, Uint1Value, Uint2Value, Uint4Value, Uint8Value, Utf8Value, Uuid4Value, Uuid7Value, Value, type ValueRole, type ValueShapeNode, asFrameResults, cellText, columnsToRows, decode, displayWidth, encodeParams, encodeValue, formatValue, graphemeWidth, inferColumns, isOptionType, padToWidth, parseValue, planTable, tokenizeRql, transformFrames, transformResult, truncateToWidth, typeNameFromCode, unwrapOptionType, validateShape, valueRole, valueTypeName };
+export { type ArrayShapeNode, type BaseType, BlobValue, BooleanValue, type Column, type ColumnAlign, DateTimeValue, DateValue, DecimalValue, type Diagnostic, type DiagnosticColumn, DurationValue, type ErrorResponse, Float4Value, Float8Value, type Fragment, type Frame, type FrameResults, IdentityIdValue, type InferShape, type InferShapes, Int16Value, Int1Value, Int2Value, Int4Value, Int8Value, type MissingPresentation, NONE_PRESENTATION, NONE_VALUE, NoneValue, type ObjectShapeNode, Option, type OptionShapeNode, type OptionType, type Params, type PlannedColumn, type PrimitiveShapeNode, type PrimitiveToTS, type PrimitiveToValue, ROW_NUMBER_KEY, RQL_KEYWORDS, RQL_LITERALS, RQL_OPERATORS, RQL_SYSTEM_COLUMNS, RQL_TYPES, ReifyError, type ResultColumn, type RqlToken, type RqlTokenKind, Shape, ShapeBuilder, ShapeMismatch, type ShapeNode, type SingleFrameResult, TYPE_CODE, type TableLayoutOptions, type TablePlan, TimeValue, type Type, type TypeName, type TypeValuePair, Uint16Value, Uint1Value, Uint2Value, Uint4Value, Uint8Value, Utf8Value, Uuid4Value, Uuid7Value, Value, type ValueRole, type ValueShapeNode, type WireType, asFrameResults, cellText, checkFrame, checkFrames, columnsFromWire, columnsToRows, decode, displayWidth, encodeParams, encodeValue, envelopeToColumns, envelopesToFrames, formatValue, framesFromWire, graphemeWidth, inferColumns, innerOfOption, isOption, isOptionType, noneDepth, noneMarker, noneMarkerDepth, optionDepth, padToWidth, parseValue, planTable, tokenizeRql, transformFrames, transformResult, truncateToWidth, typeFromWire, typeNameFromCode, typeToWire, unwrapOptionType, validateShape, valueRole, valueTypeName };