@reifydb/core 0.9.0 → 0.9.2

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 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";
 
 /**
  * A binary large object (BLOB) value that can hold arbitrary byte data.
@@ -288,7 +291,7 @@ declare class DateTimeValue implements Value {
     /**
      * Get Unix timestamp in seconds
      */
-    to_epoch_secs(): number | undefined;
+    toEpochSecs(): number | undefined;
     /**
      * Get Unix timestamp in nanoseconds
      */
@@ -708,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;
@@ -720,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;
@@ -912,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;
@@ -919,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;
@@ -929,50 +992,64 @@ declare abstract class Value {
     abstract equals(other: Value): boolean;
 }
 
-declare function decode(pair: TypeValuePair): Value;
-
-declare const TYPE_CODE: {
-    readonly None: 0;
-    readonly Boolean: 1;
-    readonly Float4: 2;
-    readonly Float8: 3;
-    readonly Int1: 4;
-    readonly Int2: 5;
-    readonly Int4: 6;
-    readonly Int8: 7;
-    readonly Int16: 8;
-    readonly Utf8: 9;
-    readonly Uint1: 10;
-    readonly Uint2: 11;
-    readonly Uint4: 12;
-    readonly Uint8: 13;
-    readonly Uint16: 14;
-    readonly Date: 15;
-    readonly DateTime: 16;
-    readonly Time: 17;
-    readonly Duration: 18;
-    readonly IdentityId: 19;
-    readonly Uuid4: 20;
-    readonly Uuid7: 21;
-    readonly Blob: 22;
-    readonly Int: 23;
-    readonly Uint: 24;
-    readonly Decimal: 25;
-    readonly Any: 26;
-    readonly DictionaryId: 27;
-    readonly Type: 28;
-    readonly List: 29;
-    readonly Record: 30;
-    readonly Tuple: 31;
-};
-type TypeName = keyof typeof TYPE_CODE;
-declare function type_name_from_code(code: number): TypeName;
-
-type PrimitiveToTS<T extends BaseType> = T extends 'Blob' ? Uint8Array : T extends 'Boolean' ? boolean : T extends 'Decimal' ? string : T extends 'Float4' ? number : T extends 'Float8' ? number : T extends 'Int1' ? number : T extends 'Int2' ? number : T extends 'Int4' ? number : T extends 'Int8' ? bigint : T extends 'Int16' ? bigint : T extends 'Uint1' ? number : T extends 'Uint2' ? number : T extends 'Uint4' ? number : T extends 'Uint8' ? bigint : T extends 'Uint16' ? bigint : T extends 'Utf8' ? string : T extends 'Date' ? Date : T extends 'DateTime' ? Date : T extends 'Time' ? string : T extends 'Duration' ? string : T extends 'Uuid4' ? string : T extends 'Uuid7' ? string : T extends 'None' ? undefined : T extends 'IdentityId' ? string : never;
-type PrimitiveToValue<T extends BaseType> = T extends 'Blob' ? BlobValue : T extends 'Boolean' ? BooleanValue : T extends 'Decimal' ? DecimalValue : T extends 'Float4' ? Float4Value : T extends 'Float8' ? Float8Value : T extends 'Int1' ? Int1Value : T extends 'Int2' ? Int2Value : T extends 'Int4' ? Int4Value : T extends 'Int8' ? Int8Value : T extends 'Int16' ? Int16Value : T extends 'Uint1' ? Uint1Value : T extends 'Uint2' ? Uint2Value : T extends 'Uint4' ? Uint4Value : T extends 'Uint8' ? Uint8Value : T extends 'Uint16' ? Uint16Value : T extends 'Utf8' ? Utf8Value : T extends 'Date' ? DateValue : T extends 'DateTime' ? DateTimeValue : T extends 'Time' ? TimeValue : T extends 'Duration' ? DurationValue : T extends 'Uuid4' ? Uuid4Value : T extends 'Uuid7' ? Uuid7Value : T extends 'None' ? NoneValue : T extends 'IdentityId' ? IdentityIdValue : never;
+interface PrimitiveTSMap {
+    Blob: Uint8Array;
+    Boolean: boolean;
+    Decimal: string;
+    Float4: number;
+    Float8: number;
+    Int1: number;
+    Int2: number;
+    Int4: number;
+    Int8: bigint;
+    Int16: bigint;
+    Uint1: number;
+    Uint2: number;
+    Uint4: number;
+    Uint8: bigint;
+    Uint16: bigint;
+    Utf8: string;
+    Date: Date;
+    DateTime: Date;
+    Time: string;
+    Duration: string;
+    Uuid4: string;
+    Uuid7: string;
+    None: undefined;
+    IdentityId: string;
+}
+interface PrimitiveValueMap {
+    Blob: BlobValue;
+    Boolean: BooleanValue;
+    Decimal: DecimalValue;
+    Float4: Float4Value;
+    Float8: Float8Value;
+    Int1: Int1Value;
+    Int2: Int2Value;
+    Int4: Int4Value;
+    Int8: Int8Value;
+    Int16: Int16Value;
+    Uint1: Uint1Value;
+    Uint2: Uint2Value;
+    Uint4: Uint4Value;
+    Uint8: Uint8Value;
+    Uint16: Uint16Value;
+    Utf8: Utf8Value;
+    Date: DateValue;
+    DateTime: DateTimeValue;
+    Time: TimeValue;
+    Duration: DurationValue;
+    Uuid4: Uuid4Value;
+    Uuid7: Uuid7Value;
+    None: NoneValue;
+    IdentityId: IdentityIdValue;
+}
+type PrimitiveToTS<T extends BaseType> = PrimitiveTSMap[T];
+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]: InferShape<P[K]>;
-} : S extends ArrayShapeNode<infer T> ? InferShape<T>[] : S extends OptionalShapeNode<infer T> ? InferShape<T> | undefined : never;
+    [K in keyof P as CamelCase<K & string>]: InferShape<P[K]>;
+} : 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]>[];
 };
@@ -1011,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'>;
@@ -1044,6 +1121,15 @@ declare function parseValue(shape: ShapeNode, value: any): any;
 
 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;
@@ -1056,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 {
@@ -1128,4 +1214,109 @@ type SingleFrameResult<S extends ShapeNode> = InferShape<S>[];
  */
 declare function asFrameResults<S extends readonly ShapeNode[]>(results: any): FrameResults<S>;
 
-export { type ArrayShapeNode, type BaseType, BlobValue, BooleanValue, type Column, 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, NONE_VALUE, NoneValue, type ObjectShapeNode, type OptionType, type OptionalShapeNode, type Params, type PrimitiveShapeNode, type PrimitiveToTS, type PrimitiveToValue, ReifyError, Shape, ShapeBuilder, type ShapeNode, type SingleFrameResult, TYPE_CODE, TimeValue, type Type, type TypeName, type TypeValuePair, Uint16Value, Uint1Value, Uint2Value, Uint4Value, Uint8Value, Utf8Value, Uuid4Value, Uuid7Value, Value, type ValueShapeNode, asFrameResults, decode, isOptionType, parseValue, type_name_from_code, unwrapOptionType, validateShape };
+declare function decode(pair: TypeValuePair): Value;
+declare function columnsToRows(columns: Column[]): Record<string, Value>[];
+
+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;
+    readonly Boolean: 1;
+    readonly Float4: 2;
+    readonly Float8: 3;
+    readonly Int1: 4;
+    readonly Int2: 5;
+    readonly Int4: 6;
+    readonly Int8: 7;
+    readonly Int16: 8;
+    readonly Utf8: 9;
+    readonly Uint1: 10;
+    readonly Uint2: 11;
+    readonly Uint4: 12;
+    readonly Uint8: 13;
+    readonly Uint16: 14;
+    readonly Date: 15;
+    readonly DateTime: 16;
+    readonly Time: 17;
+    readonly Duration: 18;
+    readonly IdentityId: 19;
+    readonly Uuid4: 20;
+    readonly Uuid7: 21;
+    readonly Blob: 22;
+    readonly Int: 23;
+    readonly Uint: 24;
+    readonly Decimal: 25;
+    readonly Any: 26;
+    readonly DictionaryId: 27;
+    readonly Type: 28;
+    readonly List: 29;
+    readonly Record: 30;
+    readonly Tuple: 31;
+};
+type TypeName = keyof typeof TYPE_CODE;
+declare function typeNameFromCode(code: number): TypeName;
+
+interface MissingPresentation {
+    text: string;
+    italic: boolean;
+    muted: boolean;
+}
+declare const NONE_PRESENTATION: MissingPresentation;
+type ValueRole = 'none' | 'boolean' | 'number' | 'temporal' | 'uuid' | 'string' | 'blob' | 'unknown';
+declare function valueTypeName(value: unknown): string | undefined;
+declare function valueRole(value: unknown): ValueRole;
+declare function formatValue(value: unknown): string;
+
+declare function graphemeWidth(grapheme: string): number;
+declare function displayWidth(text: string): number;
+declare function truncateToWidth(text: string, width: number, ellipsis?: string): string;
+declare function padToWidth(text: string, width: number, align: 'left' | 'right' | 'center'): string;
+
+type ColumnAlign = 'left' | 'right';
+interface ResultColumn {
+    name: string;
+    type?: string;
+    role: ValueRole;
+    align: ColumnAlign;
+}
+interface PlannedColumn {
+    column: ResultColumn;
+    width: number;
+}
+interface TablePlan {
+    columns: PlannedColumn[];
+    dropped: ResultColumn[];
+    truncated: boolean;
+}
+interface TableLayoutOptions {
+    width?: number;
+    maxColumnWidth?: number;
+    sample?: number;
+    columnOverhead?: number;
+    tableOverhead?: number;
+}
+declare function inferColumns(rows: ReadonlyArray<Record<string, unknown>>): ResultColumn[];
+declare function planTable(rows: ReadonlyArray<Record<string, unknown>>, columns: ReadonlyArray<ResultColumn>, options?: TableLayoutOptions): TablePlan;
+declare function cellText(value: unknown, width: number): string;
+
+declare const RQL_KEYWORDS: readonly string[];
+declare const RQL_LITERALS: readonly string[];
+declare const RQL_TYPES: readonly string[];
+declare const RQL_OPERATORS: readonly string[];
+declare const RQL_SYSTEM_COLUMNS: readonly string[];
+
+type RqlTokenKind = 'keyword' | 'type' | 'constant' | 'identifier' | 'namespace' | 'entity' | 'function' | 'key' | 'variable' | 'variable.predefined' | 'comment' | 'string' | 'number' | 'operator' | 'delimiter' | 'bracket' | 'white';
+interface RqlToken {
+    kind: RqlTokenKind;
+    start: number;
+    end: number;
+}
+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, 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 };