@tinybirdco/sdk 0.0.1

package/dist/schema/datasource.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect } from "vitest";
+import { defineDatasource, isDatasourceDefinition, getColumnType, getColumnJsonPath, getColumnNames, column, } from "./datasource.js";
+import { t } from "./types.js";
+import { engine } from "./engines.js";
+describe("Datasource Schema", () => {
+    describe("defineDatasource", () => {
+        it("creates a datasource with required fields", () => {
+            const ds = defineDatasource("events", {
+                schema: {
+                    id: t.string(),
+                    timestamp: t.dateTime(),
+                },
+            });
+            expect(ds._name).toBe("events");
+            expect(ds._type).toBe("datasource");
+            expect(ds.options.schema).toBeDefined();
+        });
+        it("creates a datasource with description", () => {
+            const ds = defineDatasource("events", {
+                description: "Event tracking data",
+                schema: {
+                    id: t.string(),
+                },
+            });
+            expect(ds.options.description).toBe("Event tracking data");
+        });
+        it("creates a datasource with engine configuration", () => {
+            const ds = defineDatasource("events", {
+                schema: {
+                    id: t.string(),
+                    timestamp: t.dateTime(),
+                },
+                engine: engine.mergeTree({
+                    sortingKey: ["id", "timestamp"],
+                    partitionKey: "toYYYYMM(timestamp)",
+                }),
+            });
+            expect(ds.options.engine).toBeDefined();
+            expect(ds.options.engine?.type).toBe("MergeTree");
+        });
+        it("throws error for invalid datasource name", () => {
+            expect(() => defineDatasource("123invalid", {
+                schema: { id: t.string() },
+            })).toThrow("Invalid datasource name");
+            expect(() => defineDatasource("my-datasource", {
+                schema: { id: t.string() },
+            })).toThrow("Invalid datasource name");
+            expect(() => defineDatasource("", {
+                schema: { id: t.string() },
+            })).toThrow("Invalid datasource name");
+        });
+        it("allows valid naming patterns", () => {
+            // Underscore prefix
+            const ds1 = defineDatasource("_private", {
+                schema: { id: t.string() },
+            });
+            expect(ds1._name).toBe("_private");
+            // With numbers
+            const ds2 = defineDatasource("events_v2", {
+                schema: { id: t.string() },
+            });
+            expect(ds2._name).toBe("events_v2");
+        });
+    });
+    describe("isDatasourceDefinition", () => {
+        it("returns true for valid datasource", () => {
+            const ds = defineDatasource("events", {
+                schema: { id: t.string() },
+            });
+            expect(isDatasourceDefinition(ds)).toBe(true);
+        });
+        it("returns false for non-datasource objects", () => {
+            expect(isDatasourceDefinition({})).toBe(false);
+            expect(isDatasourceDefinition(null)).toBe(false);
+            expect(isDatasourceDefinition(undefined)).toBe(false);
+            expect(isDatasourceDefinition("string")).toBe(false);
+            expect(isDatasourceDefinition(123)).toBe(false);
+            expect(isDatasourceDefinition({ _name: "test" })).toBe(false);
+        });
+    });
+    describe("getColumnType", () => {
+        it("returns type from raw validator", () => {
+            const validator = t.string();
+            const result = getColumnType(validator);
+            expect(result).toBe(validator);
+        });
+        it("returns type from column definition", () => {
+            const validator = t.string();
+            const col = column(validator, { jsonPath: "$.id" });
+            const result = getColumnType(col);
+            expect(result).toBe(validator);
+        });
+    });
+    describe("getColumnJsonPath", () => {
+        it("returns undefined for raw validator", () => {
+            const validator = t.string();
+            const result = getColumnJsonPath(validator);
+            expect(result).toBeUndefined();
+        });
+        it("returns jsonPath from column definition", () => {
+            const col = column(t.string(), { jsonPath: "$.user.id" });
+            const result = getColumnJsonPath(col);
+            expect(result).toBe("$.user.id");
+        });
+        it("returns undefined when jsonPath is not set", () => {
+            const col = column(t.string());
+            const result = getColumnJsonPath(col);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe("getColumnNames", () => {
+        it("returns all column names from schema", () => {
+            const schema = {
+                id: t.string(),
+                timestamp: t.dateTime(),
+                user_id: t.string(),
+            };
+            const names = getColumnNames(schema);
+            expect(names).toHaveLength(3);
+            expect(names).toContain("id");
+            expect(names).toContain("timestamp");
+            expect(names).toContain("user_id");
+        });
+        it("returns empty array for empty schema", () => {
+            const names = getColumnNames({});
+            expect(names).toHaveLength(0);
+        });
+    });
+    describe("column", () => {
+        it("creates a column definition with type only", () => {
+            const col = column(t.string());
+            expect(col.type).toBeDefined();
+            expect(col.jsonPath).toBeUndefined();
+        });
+        it("creates a column definition with jsonPath", () => {
+            const col = column(t.string(), { jsonPath: "$.data.value" });
+            expect(col.type).toBeDefined();
+            expect(col.jsonPath).toBe("$.data.value");
+        });
+    });
+});
+//# sourceMappingURL=datasource.test.js.map

package/dist/schema/datasource.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource.test.js","sourceRoot":"","sources":["../../src/schema/datasource.test.ts"],"names":[],"mappings":"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"}

package/dist/schema/engines.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Engine configurations for Tinybird datasources
+ * ClickHouse table engines determine how data is stored and queried
+ */
+/**
+ * Base configuration shared by all MergeTree engines
+ */
+export interface BaseMergeTreeConfig {
+    /** Columns used for sorting data within parts (required for all MergeTree engines) */
+    sortingKey: string | readonly string[];
+    /** Expression for partitioning data (e.g., 'toYYYYMM(timestamp)') */
+    partitionKey?: string;
+    /** Primary key columns (defaults to sortingKey if not specified) */
+    primaryKey?: string | readonly string[];
+    /** TTL expression for automatic data expiration (e.g., 'timestamp + INTERVAL 90 DAY') */
+    ttl?: string;
+    /** Additional engine settings */
+    settings?: Record<string, string | number | boolean>;
+}
+/**
+ * MergeTree engine configuration
+ * The most universal and functional table engine for high-load tasks
+ */
+export interface MergeTreeConfig extends BaseMergeTreeConfig {
+    type: "MergeTree";
+}
+/**
+ * ReplacingMergeTree engine configuration
+ * Removes duplicate rows with the same sorting key during merges
+ */
+export interface ReplacingMergeTreeConfig extends BaseMergeTreeConfig {
+    type: "ReplacingMergeTree";
+    /** Optional version column - rows with highest version are kept */
+    ver?: string;
+    /** Optional flag to enable clean mode (ClickHouse 23.2+) */
+    isDeleted?: string;
+}
+/**
+ * SummingMergeTree engine configuration
+ * Sums numeric columns for rows with the same sorting key during merges
+ */
+export interface SummingMergeTreeConfig extends BaseMergeTreeConfig {
+    type: "SummingMergeTree";
+    /** Columns to sum (if not specified, all numeric columns are summed) */
+    columns?: readonly string[];
+}
+/**
+ * AggregatingMergeTree engine configuration
+ * For incremental data aggregation with AggregateFunction columns
+ */
+export interface AggregatingMergeTreeConfig extends BaseMergeTreeConfig {
+    type: "AggregatingMergeTree";
+}
+/**
+ * CollapsingMergeTree engine configuration
+ * For collapsing rows that cancel each other out
+ */
+export interface CollapsingMergeTreeConfig extends BaseMergeTreeConfig {
+    type: "CollapsingMergeTree";
+    /** Column containing sign (1 for state, -1 for cancel) */
+    sign: string;
+}
+/**
+ * VersionedCollapsingMergeTree engine configuration
+ * For collapsing with versioning when events may arrive out of order
+ */
+export interface VersionedCollapsingMergeTreeConfig extends BaseMergeTreeConfig {
+    type: "VersionedCollapsingMergeTree";
+    /** Column containing sign (1 for state, -1 for cancel) */
+    sign: string;
+    /** Column containing version number */
+    version: string;
+}
+/**
+ * Union type of all engine configurations
+ */
+export type EngineConfig = MergeTreeConfig | ReplacingMergeTreeConfig | SummingMergeTreeConfig | AggregatingMergeTreeConfig | CollapsingMergeTreeConfig | VersionedCollapsingMergeTreeConfig;
+/**
+ * Engine configuration builders
+ *
+ * @example
+ * ```ts
+ * import { engine } from '@tinybirdco/sdk';
+ *
+ * // Basic MergeTree
+ * engine.mergeTree({
+ *   sortingKey: ['user_id', 'timestamp'],
+ *   partitionKey: 'toYYYYMM(timestamp)',
+ * });
+ *
+ * // ReplacingMergeTree for upserts
+ * engine.replacingMergeTree({
+ *   sortingKey: ['id'],
+ *   ver: 'updated_at',
+ * });
+ *
+ * // SummingMergeTree for counters
+ * engine.summingMergeTree({
+ *   sortingKey: ['date', 'metric_name'],
+ *   columns: ['value'],
+ * });
+ * ```
+ */
+export declare const engine: {
+    /**
+     * MergeTree - The most universal engine for high-load tasks
+     * Best for: General-purpose analytics, logs, events
+     */
+    readonly mergeTree: (config: Omit<MergeTreeConfig, "type">) => MergeTreeConfig;
+    /**
+     * ReplacingMergeTree - Removes duplicates during background merges
+     * Best for: Maintaining latest state, upserts, slowly changing dimensions
+     *
+     * @param config.ver - Optional version column. Rows with highest version are kept.
+     */
+    readonly replacingMergeTree: (config: Omit<ReplacingMergeTreeConfig, "type">) => ReplacingMergeTreeConfig;
+    /**
+     * SummingMergeTree - Sums numeric columns during background merges
+     * Best for: Counters, metrics aggregation, pre-aggregated data
+     *
+     * @param config.columns - Columns to sum. If not specified, all numeric columns are summed.
+     */
+    readonly summingMergeTree: (config: Omit<SummingMergeTreeConfig, "type">) => SummingMergeTreeConfig;
+    /**
+     * AggregatingMergeTree - For incremental aggregation with AggregateFunction columns
+     * Best for: Materialized views, incremental aggregation pipelines
+     */
+    readonly aggregatingMergeTree: (config: Omit<AggregatingMergeTreeConfig, "type">) => AggregatingMergeTreeConfig;
+    /**
+     * CollapsingMergeTree - For collapsing state/cancel row pairs
+     * Best for: Changelog-style updates, mutable data with deletes
+     *
+     * @param config.sign - Column containing 1 (state) or -1 (cancel)
+     */
+    readonly collapsingMergeTree: (config: Omit<CollapsingMergeTreeConfig, "type">) => CollapsingMergeTreeConfig;
+    /**
+     * VersionedCollapsingMergeTree - Collapsing with versioning for out-of-order events
+     * Best for: Changelog-style updates with potential out-of-order arrival
+     *
+     * @param config.sign - Column containing 1 (state) or -1 (cancel)
+     * @param config.version - Column containing version number for ordering
+     */
+    readonly versionedCollapsingMergeTree: (config: Omit<VersionedCollapsingMergeTreeConfig, "type">) => VersionedCollapsingMergeTreeConfig;
+};
+/**
+ * Get the sorting key as an array
+ */
+export declare function getSortingKey(config: EngineConfig): readonly string[];
+/**
+ * Get the primary key as an array (defaults to sorting key)
+ */
+export declare function getPrimaryKey(config: EngineConfig): readonly string[];
+/**
+ * Generate the engine clause for a datasource file
+ */
+export declare function getEngineClause(config: EngineConfig): string;
+//# sourceMappingURL=engines.d.ts.map

package/dist/schema/engines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.d.ts","sourceRoot":"","sources":["../../src/schema/engines.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACvC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACxC,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACtD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,IAAI,EAAE,kBAAkB,CAAC;IACzB,wEAAwE;IACxE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,IAAI,EAAE,sBAAsB,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,kCAAmC,SAAQ,mBAAmB;IAC7E,IAAI,EAAE,8BAA8B,CAAC;IACrC,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,eAAe,GACf,wBAAwB,GACxB,sBAAsB,GACtB,0BAA0B,GAC1B,yBAAyB,GACzB,kCAAkC,CAAC;AASvC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,MAAM;IACjB;;;OAGG;iCACiB,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,KAAG,eAAe;IAKnE;;;;;OAKG;0CAEO,IAAI,CAAC,wBAAwB,EAAE,MAAM,CAAC,KAC7C,wBAAwB;IAK3B;;;;;OAKG;wCAEO,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,KAC3C,sBAAsB;IAKzB;;;OAGG;4CAEO,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,KAC/C,0BAA0B;IAK7B;;;;;OAKG;2CAEO,IAAI,CAAC,yBAAyB,EAAE,MAAM,CAAC,KAC9C,yBAAyB;IAK5B;;;;;;OAMG;oDAEO,IAAI,CAAC,kCAAkC,EAAE,MAAM,CAAC,KACvD,kCAAkC;CAI7B,CAAC;AAEX;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAErE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAKrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAkD5D"}

package/dist/schema/engines.js

@@ -0,0 +1,155 @@
+/**
+ * Engine configurations for Tinybird datasources
+ * ClickHouse table engines determine how data is stored and queried
+ */
+/**
+ * Helper to normalize sorting key to array format
+ */
+function normalizeSortingKey(key) {
+    return typeof key === "string" ? [key] : key;
+}
+/**
+ * Engine configuration builders
+ *
+ * @example
+ * ```ts
+ * import { engine } from '@tinybirdco/sdk';
+ *
+ * // Basic MergeTree
+ * engine.mergeTree({
+ *   sortingKey: ['user_id', 'timestamp'],
+ *   partitionKey: 'toYYYYMM(timestamp)',
+ * });
+ *
+ * // ReplacingMergeTree for upserts
+ * engine.replacingMergeTree({
+ *   sortingKey: ['id'],
+ *   ver: 'updated_at',
+ * });
+ *
+ * // SummingMergeTree for counters
+ * engine.summingMergeTree({
+ *   sortingKey: ['date', 'metric_name'],
+ *   columns: ['value'],
+ * });
+ * ```
+ */
+export const engine = {
+    /**
+     * MergeTree - The most universal engine for high-load tasks
+     * Best for: General-purpose analytics, logs, events
+     */
+    mergeTree: (config) => ({
+        type: "MergeTree",
+        ...config,
+    }),
+    /**
+     * ReplacingMergeTree - Removes duplicates during background merges
+     * Best for: Maintaining latest state, upserts, slowly changing dimensions
+     *
+     * @param config.ver - Optional version column. Rows with highest version are kept.
+     */
+    replacingMergeTree: (config) => ({
+        type: "ReplacingMergeTree",
+        ...config,
+    }),
+    /**
+     * SummingMergeTree - Sums numeric columns during background merges
+     * Best for: Counters, metrics aggregation, pre-aggregated data
+     *
+     * @param config.columns - Columns to sum. If not specified, all numeric columns are summed.
+     */
+    summingMergeTree: (config) => ({
+        type: "SummingMergeTree",
+        ...config,
+    }),
+    /**
+     * AggregatingMergeTree - For incremental aggregation with AggregateFunction columns
+     * Best for: Materialized views, incremental aggregation pipelines
+     */
+    aggregatingMergeTree: (config) => ({
+        type: "AggregatingMergeTree",
+        ...config,
+    }),
+    /**
+     * CollapsingMergeTree - For collapsing state/cancel row pairs
+     * Best for: Changelog-style updates, mutable data with deletes
+     *
+     * @param config.sign - Column containing 1 (state) or -1 (cancel)
+     */
+    collapsingMergeTree: (config) => ({
+        type: "CollapsingMergeTree",
+        ...config,
+    }),
+    /**
+     * VersionedCollapsingMergeTree - Collapsing with versioning for out-of-order events
+     * Best for: Changelog-style updates with potential out-of-order arrival
+     *
+     * @param config.sign - Column containing 1 (state) or -1 (cancel)
+     * @param config.version - Column containing version number for ordering
+     */
+    versionedCollapsingMergeTree: (config) => ({
+        type: "VersionedCollapsingMergeTree",
+        ...config,
+    }),
+};
+/**
+ * Get the sorting key as an array
+ */
+export function getSortingKey(config) {
+    return normalizeSortingKey(config.sortingKey);
+}
+/**
+ * Get the primary key as an array (defaults to sorting key)
+ */
+export function getPrimaryKey(config) {
+    if (config.primaryKey) {
+        return normalizeSortingKey(config.primaryKey);
+    }
+    return getSortingKey(config);
+}
+/**
+ * Generate the engine clause for a datasource file
+ */
+export function getEngineClause(config) {
+    const parts = [`ENGINE "${config.type}"`];
+    if (config.partitionKey) {
+        parts.push(`ENGINE_PARTITION_KEY "${config.partitionKey}"`);
+    }
+    const sortingKey = getSortingKey(config);
+    parts.push(`ENGINE_SORTING_KEY "${sortingKey.join(", ")}"`);
+    if (config.primaryKey) {
+        const primaryKey = getPrimaryKey(config);
+        parts.push(`ENGINE_PRIMARY_KEY "${primaryKey.join(", ")}"`);
+    }
+    if (config.ttl) {
+        parts.push(`ENGINE_TTL "${config.ttl}"`);
+    }
+    // Engine-specific options
+    if (config.type === "ReplacingMergeTree" && config.ver) {
+        parts.push(`ENGINE_VER "${config.ver}"`);
+    }
+    if (config.type === "CollapsingMergeTree" || config.type === "VersionedCollapsingMergeTree") {
+        parts.push(`ENGINE_SIGN "${config.sign}"`);
+    }
+    if (config.type === "VersionedCollapsingMergeTree") {
+        parts.push(`ENGINE_VERSION "${config.version}"`);
+    }
+    if (config.type === "SummingMergeTree" && config.columns && config.columns.length > 0) {
+        parts.push(`ENGINE_SUMMING_COLUMNS "${config.columns.join(", ")}"`);
+    }
+    if (config.settings && Object.keys(config.settings).length > 0) {
+        const settingsStr = Object.entries(config.settings)
+            .map(([k, v]) => {
+            if (typeof v === "string") {
+                const escaped = v.replace(/'/g, "\\'");
+                return `${k}='${escaped}'`;
+            }
+            return `${k}=${v}`;
+        })
+            .join(", ");
+        parts.push(`ENGINE_SETTINGS "${settingsStr}"`);
+    }
+    return parts.join("\n");
+}
+//# sourceMappingURL=engines.js.map

package/dist/schema/engines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.js","sourceRoot":"","sources":["../../src/schema/engines.ts"],"names":[],"mappings":"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"}

package/dist/schema/engines.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engines.test.d.ts.map

package/dist/schema/engines.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.test.d.ts","sourceRoot":"","sources":["../../src/schema/engines.test.ts"],"names":[],"mappings":""}