@tinybirdco/sdk 0.0.1

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * @tinybirdco/sdk - TypeScript SDK for Tinybird Forward
+ *
+ * Define datasources and pipes as TypeScript with full type safety.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   defineDatasource,
+ *   definePipe,
+ *   defineProject,
+ *   node,
+ *   t,
+ *   p,
+ *   engine,
+ *   createClient,
+ * } from '@tinybirdco/sdk';
+ *
+ * // Define a datasource
+ * const events = defineDatasource('events', {
+ *   schema: {
+ *     timestamp: t.dateTime(),
+ *     user_id: t.string(),
+ *     event_type: t.string().lowCardinality(),
+ *   },
+ *   engine: engine.mergeTree({
+ *     sortingKey: ['user_id', 'timestamp'],
+ *   }),
+ * });
+ *
+ * // Define a pipe
+ * const topEvents = definePipe('top_events', {
+ *   params: {
+ *     limit: p.int32().optional(10),
+ *   },
+ *   nodes: [
+ *     node({
+ *       name: 'aggregated',
+ *       sql: 'SELECT event_type, count() as cnt FROM events GROUP BY event_type LIMIT {{Int32(limit, 10)}}',
+ *     }),
+ *   ],
+ *   output: {
+ *     event_type: t.string(),
+ *     cnt: t.uint64(),
+ *   },
+ *   endpoint: true,
+ * });
+ *
+ * // Create project
+ * export default defineProject({
+ *   datasources: { events },
+ *   pipes: { topEvents },
+ * });
+ * ```
+ */
+
+// ============ Schema Types ============
+export { t } from "./schema/types.js";
+export type {
+  TypeValidator,
+  AnyTypeValidator,
+  TypeModifiers,
+  InferType,
+  TinybirdType,
+} from "./schema/types.js";
+export {
+  isTypeValidator,
+  getTinybirdType,
+  getModifiers,
+} from "./schema/types.js";
+
+// ============ Parameter Types ============
+export { p } from "./schema/params.js";
+export type {
+  ParamValidator,
+  AnyParamValidator,
+  InferParamType,
+} from "./schema/params.js";
+export {
+  isParamValidator,
+  getParamTinybirdType,
+  isParamRequired,
+  getParamDefault,
+  getParamDescription,
+} from "./schema/params.js";
+
+// ============ Engine Configurations ============
+export { engine, getEngineClause, getSortingKey, getPrimaryKey } from "./schema/engines.js";
+export type {
+  EngineConfig,
+  BaseMergeTreeConfig,
+  MergeTreeConfig,
+  ReplacingMergeTreeConfig,
+  SummingMergeTreeConfig,
+  AggregatingMergeTreeConfig,
+  CollapsingMergeTreeConfig,
+  VersionedCollapsingMergeTreeConfig,
+} from "./schema/engines.js";
+
+// ============ Datasource ============
+export { defineDatasource, isDatasourceDefinition, column, getColumnType, getColumnJsonPath, getColumnNames } from "./schema/datasource.js";
+export type {
+  DatasourceDefinition,
+  DatasourceOptions,
+  SchemaDefinition,
+  ColumnDefinition,
+  TokenConfig,
+  ExtractSchema,
+} from "./schema/datasource.js";
+
+// ============ Pipe ============
+export {
+  definePipe,
+  defineEndpoint,
+  defineMaterializedView,
+  defineCopyPipe,
+  node,
+  isPipeDefinition,
+  isNodeDefinition,
+  getEndpointConfig,
+  getMaterializedConfig,
+  getCopyConfig,
+  isMaterializedView,
+  isCopyPipe,
+  getNodeNames,
+  getNode,
+  sql,
+} from "./schema/pipe.js";
+export type {
+  PipeDefinition,
+  PipeOptions,
+  EndpointOptions,
+  CopyPipeOptions,
+  CopyConfig,
+  NodeDefinition,
+  NodeOptions,
+  ParamsDefinition,
+  OutputDefinition,
+  EndpointConfig,
+  MaterializedConfig,
+  MaterializedViewOptions,
+  PipeTokenConfig,
+  ExtractParams,
+  ExtractOutput,
+} from "./schema/pipe.js";
+
+// ============ Project ============
+export { defineProject, isProjectDefinition, getDatasourceNames, getPipeNames, getDatasource, getPipe, createTinybirdClient } from "./schema/project.js";
+export type {
+  ProjectDefinition,
+  ProjectConfig,
+  ProjectClient,
+  TinybirdClientConfig,
+  DatasourcesDefinition,
+  PipesDefinition,
+  ExtractDatasources,
+  ExtractPipes,
+  DataModel,
+} from "./schema/project.js";
+
+// ============ Type Inference ============
+export type {
+  Infer,
+  InferRow,
+  InferParams,
+  InferOutput,
+  InferOutputRow,
+  InferEvent,
+  PartialRow,
+  InferSchema,
+  InferTinybirdTypes,
+  InferMaterializedTarget,
+  InferMaterializedTargetRow,
+  IsMaterializedPipe,
+} from "./infer/index.js";
+
+// ============ Client ============
+export { TinybirdClient, createClient } from "./client/base.js";
+export { TinybirdError } from "./client/types.js";
+export type {
+  ClientConfig,
+  QueryResult,
+  IngestResult,
+  QueryOptions,
+  IngestOptions,
+  ColumnMeta,
+  QueryStatistics,
+  TinybirdErrorResponse,
+  TypedPipeEndpoint,
+  TypedDatasourceIngest,
+} from "./client/types.js";

package/src/infer/index.ts

@@ -0,0 +1,247 @@
+/**
+ * Type inference utilities for extracting TypeScript types from Tinybird definitions
+ */
+
+import type { TypeValidator, TypeModifiers } from "../schema/types.js";
+import type { ParamValidator } from "../schema/params.js";
+import type { DatasourceDefinition, SchemaDefinition, ColumnDefinition } from "../schema/datasource.js";
+import type { PipeDefinition, ParamsDefinition, OutputDefinition } from "../schema/pipe.js";
+
+/**
+ * Extract the TypeScript type from a type validator
+ *
+ * @example
+ * ```ts
+ * import { t, Infer } from '@tinybirdco/sdk';
+ *
+ * const myType = t.string();
+ * type MyType = Infer<typeof myType>; // string
+ *
+ * const myArray = t.array(t.int32());
+ * type MyArray = Infer<typeof myArray>; // number[]
+ * ```
+ */
+export type Infer<T> = T extends TypeValidator<infer U, string, TypeModifiers>
+  ? U
+  : T extends ParamValidator<infer U, string, boolean>
+    ? U
+    : never;
+
+/**
+ * Infer a single column type, handling both raw validators and column definitions
+ */
+type InferColumn<T> = T extends TypeValidator<infer U, string, TypeModifiers>
+  ? U
+  : T extends { type: TypeValidator<infer U, string, TypeModifiers> }
+    ? U
+    : never;
+
+/**
+ * Extract a row type from a datasource definition
+ *
+ * @example
+ * ```ts
+ * import { defineDatasource, t, InferRow } from '@tinybirdco/sdk';
+ *
+ * const events = defineDatasource('events', {
+ *   schema: {
+ *     id: t.string(),
+ *     count: t.int32(),
+ *     timestamp: t.dateTime(),
+ *   },
+ * });
+ *
+ * type EventRow = InferRow<typeof events>;
+ * // { id: string; count: number; timestamp: Date }
+ * ```
+ */
+export type InferRow<T> = T extends DatasourceDefinition<infer S>
+  ? { [K in keyof S]: InferColumn<S[K]> }
+  : never;
+
+/**
+ * Infer a single parameter type, respecting required/optional
+ */
+type InferSingleParam<T> = T extends ParamValidator<infer U, string, infer R>
+  ? R extends true
+    ? U
+    : U | undefined
+  : never;
+
+/**
+ * Extract the required parameter keys from a params definition
+ */
+type RequiredParamKeys<T extends ParamsDefinition> = {
+  [K in keyof T]: T[K] extends ParamValidator<unknown, string, true> ? K : never;
+}[keyof T];
+
+/**
+ * Extract the optional parameter keys from a params definition
+ */
+type OptionalParamKeys<T extends ParamsDefinition> = {
+  [K in keyof T]: T[K] extends ParamValidator<unknown, string, false> ? K : never;
+}[keyof T];
+
+/**
+ * Extract the params type from a pipe definition
+ *
+ * @example
+ * ```ts
+ * import { definePipe, p, InferParams } from '@tinybirdco/sdk';
+ *
+ * const myPipe = definePipe('my_pipe', {
+ *   params: {
+ *     userId: p.string(),
+ *     limit: p.int32().optional(10),
+ *   },
+ *   nodes: [...],
+ *   output: {...},
+ * });
+ *
+ * type MyParams = InferParams<typeof myPipe>;
+ * // { userId: string; limit?: number }
+ * ```
+ */
+export type InferParams<T> = T extends PipeDefinition<infer P, OutputDefinition>
+  ? {
+      [K in RequiredParamKeys<P>]: InferSingleParam<P[K]>;
+    } & {
+      [K in OptionalParamKeys<P>]?: InferSingleParam<P[K]>;
+    }
+  : never;
+
+/**
+ * Extract the output type (single row) from a pipe definition
+ *
+ * @example
+ * ```ts
+ * import { definePipe, t, InferOutput } from '@tinybirdco/sdk';
+ *
+ * const myPipe = definePipe('my_pipe', {
+ *   params: {},
+ *   nodes: [...],
+ *   output: {
+ *     name: t.string(),
+ *     count: t.uint64(),
+ *   },
+ * });
+ *
+ * type MyOutput = InferOutput<typeof myPipe>;
+ * // { name: string; count: number }[]
+ * ```
+ */
+export type InferOutput<T> = T extends PipeDefinition<ParamsDefinition, infer O>
+  ? { [K in keyof O]: InferColumn<O[K]> }[]
+  : never;
+
+/**
+ * Extract a single output row type (without array wrapper)
+ */
+export type InferOutputRow<T> = T extends PipeDefinition<ParamsDefinition, infer O>
+  ? { [K in keyof O]: InferColumn<O[K]> }
+  : never;
+
+/**
+ * Infer the event type for ingestion (same as row type)
+ *
+ * @example
+ * ```ts
+ * import { defineDatasource, t, InferEvent } from '@tinybirdco/sdk';
+ *
+ * const events = defineDatasource('events', {
+ *   schema: {
+ *     id: t.string(),
+ *     timestamp: t.dateTime(),
+ *   },
+ * });
+ *
+ * type Event = InferEvent<typeof events>;
+ * // { id: string; timestamp: Date }
+ *
+ * // Use for type-safe event ingestion
+ * const event: Event = { id: '123', timestamp: new Date() };
+ * ```
+ */
+export type InferEvent<T> = InferRow<T>;
+
+/**
+ * Make all properties of InferRow optional (for partial updates)
+ */
+export type PartialRow<T> = T extends DatasourceDefinition<infer S>
+  ? Partial<{ [K in keyof S]: InferColumn<S[K]> }>
+  : never;
+
+/**
+ * Extract the schema definition type from a datasource
+ */
+export type InferSchema<T> = T extends DatasourceDefinition<infer S> ? S : never;
+
+/**
+ * Helper type to get the Tinybird type string for a schema
+ * Handles both raw TypeValidators and ColumnDefinition wrappers
+ */
+export type InferTinybirdTypes<T extends SchemaDefinition> = {
+  [K in keyof T]: T[K] extends ColumnDefinition<infer V>
+    ? V extends TypeValidator<unknown, infer TB, TypeModifiers>
+      ? TB
+      : never
+    : T[K] extends TypeValidator<unknown, infer TB, TypeModifiers>
+      ? TB
+      : never;
+};
+
+/**
+ * Extract the target datasource from a materialized view pipe
+ *
+ * @example
+ * ```ts
+ * import { definePipe, defineDatasource, t, engine, InferMaterializedTarget } from '@tinybirdco/sdk';
+ *
+ * const salesByHour = defineDatasource('sales_by_hour', {
+ *   schema: { day: t.date(), total: t.uint64() },
+ *   engine: engine.aggregatingMergeTree({ sortingKey: ['day'] }),
+ * });
+ *
+ * const salesMv = definePipe('sales_mv', {
+ *   nodes: [...],
+ *   output: { day: t.date(), total: t.uint64() },
+ *   materialized: { datasource: salesByHour },
+ * });
+ *
+ * type Target = InferMaterializedTarget<typeof salesMv>;
+ * // typeof salesByHour
+ * ```
+ */
+export type InferMaterializedTarget<T> = T extends PipeDefinition<
+  ParamsDefinition,
+  OutputDefinition
+>
+  ? T["options"]["materialized"] extends { datasource: infer D }
+    ? D extends DatasourceDefinition<SchemaDefinition>
+      ? D
+      : never
+    : never
+  : never;
+
+/**
+ * Extract the target datasource row type from a materialized view pipe
+ *
+ * @example
+ * ```ts
+ * type TargetRow = InferMaterializedTargetRow<typeof salesMv>;
+ * // { day: Date; total: number }
+ * ```
+ */
+export type InferMaterializedTargetRow<T> = InferRow<InferMaterializedTarget<T>>;
+
+/**
+ * Check if a pipe definition is a materialized view (type-level)
+ */
+export type IsMaterializedPipe<T> = T extends PipeDefinition<
+  ParamsDefinition,
+  OutputDefinition
+>
+  ? T["options"]["materialized"] extends { datasource: DatasourceDefinition<SchemaDefinition> }
+    ? true
+    : false
+  : false;

package/src/schema/datasource.test.ts

@@ -0,0 +1,187 @@
+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");
+    });
+  });
+});