@volter/world-core 2.0.37 → 3.0.0

package/dist/src/clickhouse/types.d.ts

@@ -0,0 +1,18 @@
+export type ClickHouseColumn = {
+    name: string;
+    type: string;
+    jsonpath?: string;
+    defaultExpr?: string;
+};
+export declare const INT_TYPES: Set<string>;
+export declare const UINT_TYPES: Set<string>;
+export declare const FLOAT_TYPES: Set<string>;
+/** Strip the wrappers a schema line may carry, reporting what they said. */
+export declare function unwrapType(type: string): {
+    base: string;
+    nullable: boolean;
+    array: boolean;
+};
+/** Type names this twin recognises in a `schema` parameter. An UNKNOWN name is refused rather than
+ *  stored verbatim: a Data Source whose column type is a typo would validate nothing forever. */
+export declare function isModeledSchemaType(type: string): boolean;

package/dist/src/clickhouse/types.js

@@ -0,0 +1,47 @@
+export const INT_TYPES = new Set(['Int8', 'Int16', 'Int32', 'Int64', 'Int128', 'Int256']);
+export const UINT_TYPES = new Set(['UInt8', 'UInt16', 'UInt32', 'UInt64', 'UInt128', 'UInt256']);
+export const FLOAT_TYPES = new Set(['Float32', 'Float64']);
+/** Strip the wrappers a schema line may carry, reporting what they said. */
+export function unwrapType(type) {
+    let t = type.trim();
+    let nullable = false;
+    let array = false;
+    // LowCardinality is a storage hint, not a value domain — peel it and keep going.
+    for (let guard = 0; guard < 4; guard++) {
+        const low = /^LowCardinality\((.*)\)$/s.exec(t);
+        if (low) {
+            t = low[1].trim();
+            continue;
+        }
+        const nul = /^Nullable\((.*)\)$/s.exec(t);
+        if (nul) {
+            nullable = true;
+            t = nul[1].trim();
+            continue;
+        }
+        const arr = /^Array\((.*)\)$/s.exec(t);
+        if (arr) {
+            array = true;
+            t = arr[1].trim();
+            continue;
+        }
+        break;
+    }
+    return { base: t, nullable, array };
+}
+/** Type names this twin recognises in a `schema` parameter. An UNKNOWN name is refused rather than
+ *  stored verbatim: a Data Source whose column type is a typo would validate nothing forever. */
+export function isModeledSchemaType(type) {
+    const { base } = unwrapType(type);
+    const head = base.replace(/\(.*\)$/s, '').trim();
+    if (KNOWN_TYPE_HEADS.has(head))
+        return true;
+    return false;
+}
+const KNOWN_TYPE_HEADS = new Set([
+    ...INT_TYPES, ...UINT_TYPES, ...FLOAT_TYPES,
+    'String', 'FixedString', 'UUID', 'IPv4', 'IPv6', 'Bool', 'Boolean',
+    'Date', 'Date32', 'DateTime', 'DateTime64', 'JSON',
+    'Decimal', 'Decimal32', 'Decimal64', 'Decimal128', 'Decimal256',
+    'Enum', 'Enum8', 'Enum16', 'Map', 'Tuple', 'Nested', 'AggregateFunction', 'SimpleAggregateFunction',
+]);

package/dist/src/clickhouse/values.d.ts

@@ -0,0 +1,146 @@
+/**
+ * A DateTime or DateTime64 value: an instant held as exact integer ticks — whole milliseconds since
+ * the epoch (`ms`) plus the nanoseconds inside that millisecond (`ns`, 0…999 999) — its scale (the
+ * `p` of `DateTime64(p)`, 0 for DateTime) and a display zone. ClickHouse stores DateTime64(p) as an
+ * Int64 count of 10^-p second ticks, so every value is truncated to its scale on construction
+ * (`makeDT`) and compares exactly.
+ */
+export declare class DT {
+    readonly ms: number;
+    readonly scale: number;
+    readonly tz?: string | undefined;
+    readonly ns: number;
+    constructor(ms: number, scale: number, tz?: string | undefined, ns?: number);
+    withTz(tz: string | undefined, scale?: number): DT;
+}
+/** A DT truncated to `scale` digits (ClickHouse's DateTime64 tick), with `ns` normalised into `ms`. */
+export declare function makeDT(ms: number, ns: number, scale: number, tz?: string): DT;
+/** Two instants' order, exactly (ms first, then the sub-millisecond nanoseconds). */
+export declare function compareDT(a: DT, b: DT): number;
+/** A bigint as the engine carries it: a number when safe, else the bigint. */
+export declare function normInt(v: bigint): number | bigint;
+/** Wrap an integer into a sized ClickHouse integer type (two's complement, as CAST/toIntN do). */
+export declare function wrapInt(v: bigint, type: string): number | bigint;
+/** An engine value as an exact integer (a float truncates toward zero, as ClickHouse's cast does). */
+export declare function toBigInt(v: unknown, type?: string): bigint;
+/** Is this an integer type of 64 bits or more (the ones `output_format_json_quote_64bit_integers` quotes)? */
+export declare function isWideIntegerType(type: string): boolean;
+/** JSON.stringify that writes a bigint as a bare JSON number (ClickHouse's unquoted 64-bit output). */
+export declare function stringifyJson(value: unknown): string;
+/** A Date value: a calendar day (days since 1970-01-01), no zone. */
+export declare class DDate {
+    readonly days: number;
+    constructor(days: number);
+}
+export type IntervalUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+export declare class Interval {
+    readonly unit: IntervalUnit;
+    readonly n: number;
+    constructor(unit: IntervalUnit, n: number);
+}
+/** A `Map(K, V)` value: its entries in the order they were written (a ClickHouse Map keeps its entries as an array of
+ *  pairs, https://clickhouse.com/docs/sql-reference/data-types/map). Stored as a JSON object of the entries. */
+export declare class ChMap {
+    readonly entries: Array<[unknown, unknown]>;
+    constructor(entries: Array<[unknown, unknown]>);
+}
+/** An aggregate function's intermediate state (`minState(x)` → `AggregateFunction(min, T)`). */
+export declare class AggState {
+    readonly fn: string;
+    readonly value: unknown;
+    constructor(fn: string, value: unknown);
+}
+export declare const SERVER_TZ = "UTC";
+/** A query the twin refuses, carrying the status + message the vendor answers with. */
+export declare class ClickHouseError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export { ClickHouseError as EngineError };
+export type Wall = {
+    y: number;
+    mo: number;
+    d: number;
+    h: number;
+    mi: number;
+    s: number;
+    ms: number;
+};
+/** The wall-clock fields of an instant in a zone. */
+export declare function wallOf(ms: number, tz?: string): Wall;
+/** The zone's UTC offset at an instant, in ms (local − UTC). */
+export declare function offsetMs(ms: number, tz?: string): number;
+/**
+ * The instant a wall-clock time names in a zone. ClickHouse's DateLUT (`makeDateTime`) adds the
+ * time of day to the day's start and, from the offset-change moment on, subtracts the change: a
+ * wall time inside a spring-forward gap therefore lands BEFORE the gap (`2024-03-10 02:30:00` in
+ * America/New_York reads back as `01:30:00` — clickhouse-local 26.10 answers the same), and a
+ * repeated fall-back hour resolves to its first occurrence. Two offset probes reproduce both.
+ */
+export declare function instantOf(w: Wall, tz?: string): number;
+export declare function daysFromCivil(y: number, mo: number, d: number): number;
+export declare function civilFromDays(days: number): {
+    y: number;
+    mo: number;
+    d: number;
+};
+/** Parse ClickHouse datetime text (and the ISO forms Tinybird's ingest accepts) in a zone, exactly:
+ *  whole milliseconds plus the nanoseconds a DateTime64(4…9) fraction carries. */
+export declare function parseDateTimeInstant(text: string, tz?: string): {
+    ms: number;
+    ns: number;
+} | undefined;
+export declare function parseDateText(text: string): number | undefined;
+export declare function formatDate(d: DDate): string;
+export declare function formatDT(v: DT): string;
+/** A DT as a Data Source stores it: wall-clock text in the column's zone, with the zone's offset
+ *  when that zone is not UTC (so an instant inside a repeated DST hour survives a round trip). */
+export declare function formatStoredDT(v: DT): string;
+/** `formatDateTime(t, fmt)` — ClickHouse's MySQL-style specifiers. */
+export declare function formatDateTimePattern(v: DT | DDate, fmt: string, tz?: string): string;
+/** Peel `LowCardinality(…)` and `Nullable(…)`. */
+export declare function baseType(type: string): {
+    base: string;
+    nullable: boolean;
+};
+export declare function typeHead(type: string): string;
+/** Split a parameterised type's top-level arguments: `Array(Nullable(String))` → [`Nullable(String)`]. */
+export declare function typeArgs(type: string): string[];
+export declare function isNullableType(type: string): boolean;
+export declare function isIntegerType(type: string): boolean;
+export declare function isUnsignedType(type: string): boolean;
+export declare function isFloatType(type: string): boolean;
+export declare function isNumberType(type: string): boolean;
+/** The zone a `DateTime('tz')` / `DateTime64(n, 'tz')` type names, if any. */
+export declare function typeZone(type: string): string | undefined;
+export declare function typeScale(type: string): number;
+/** A non-Nullable column's default value. */
+export declare function defaultOf(type: string): unknown;
+export type AggKind = 'scalar' | 'sum' | 'avg' | 'set' | 'list' | 'arg';
+export declare function aggKind(fn: string): AggKind | undefined;
+/** A stored (JSON) cell → the engine value for its column type. */
+export declare function fromStored(value: unknown, type: string): unknown;
+/**
+ * An engine value → the JSON a Data Source stores for its column type (a materialized view's
+ * insert). The value is CAST to the column type the way ClickHouse converts an INSERT … SELECT
+ * block: integers wrap to the column's width (`CAST(300 AS UInt8)` = 44) and a string that is not
+ * an integer is ClickHouse's parse error, which fails the insert.
+ */
+export declare function toStored(value: unknown, type: string): unknown;
+export declare function castDateTime(value: unknown, scale: number, tz?: string): DT;
+/** `toString(x)` — ClickHouse's text form of a value. */
+export declare function valueToText(value: unknown): string;
+/** An element inside an array's text form: strings, dates and times are single-quoted and escaped. */
+export declare function quotedText(v: unknown): string;
+/** An engine value → the JSON a `.json` response carries (a bigint stays exact). */
+export declare function toOutput(value: unknown): unknown;
+/**
+ * Compare two non-null values ClickHouse-style. A string meeting a DateTime/Date is parsed in the
+ * other side's zone (ClickHouse converts the literal to the column's type).
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+export declare function valuesEqual(a: unknown, b: unknown): boolean;
+/** A hash key under which equal values collide (for GROUP BY, JOIN, IN, uniq). */
+export declare function valueKey(v: unknown): string;
+/** A string literal meeting a DateTime in a hash key must hash as the instant. */
+export declare function valueKeyAs(v: unknown, like: unknown): string;