@tinybirdco/sdk 0.0.1

package/src/schema/params.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect } from 'vitest';
+import { p, isParamValidator, getParamTinybirdType, isParamRequired, getParamDefault, getParamDescription } from './params.js';
+
+describe('Parameter Validators (p.*)', () => {
+  describe('String types', () => {
+    it('generates String parameter', () => {
+      const param = p.string();
+      expect(param._tinybirdType).toBe('String');
+    });
+
+    it('generates UUID parameter', () => {
+      const param = p.uuid();
+      expect(param._tinybirdType).toBe('UUID');
+    });
+  });
+
+  describe('Integer types', () => {
+    it('generates Int8 parameter', () => {
+      const param = p.int8();
+      expect(param._tinybirdType).toBe('Int8');
+    });
+
+    it('generates Int16 parameter', () => {
+      const param = p.int16();
+      expect(param._tinybirdType).toBe('Int16');
+    });
+
+    it('generates Int32 parameter', () => {
+      const param = p.int32();
+      expect(param._tinybirdType).toBe('Int32');
+    });
+
+    it('generates Int64 parameter', () => {
+      const param = p.int64();
+      expect(param._tinybirdType).toBe('Int64');
+    });
+
+    it('generates UInt8 parameter', () => {
+      const param = p.uint8();
+      expect(param._tinybirdType).toBe('UInt8');
+    });
+
+    it('generates UInt16 parameter', () => {
+      const param = p.uint16();
+      expect(param._tinybirdType).toBe('UInt16');
+    });
+
+    it('generates UInt32 parameter', () => {
+      const param = p.uint32();
+      expect(param._tinybirdType).toBe('UInt32');
+    });
+
+    it('generates UInt64 parameter', () => {
+      const param = p.uint64();
+      expect(param._tinybirdType).toBe('UInt64');
+    });
+  });
+
+  describe('Float types', () => {
+    it('generates Float32 parameter', () => {
+      const param = p.float32();
+      expect(param._tinybirdType).toBe('Float32');
+    });
+
+    it('generates Float64 parameter', () => {
+      const param = p.float64();
+      expect(param._tinybirdType).toBe('Float64');
+    });
+  });
+
+  describe('Boolean type', () => {
+    it('generates Boolean parameter', () => {
+      const param = p.boolean();
+      expect(param._tinybirdType).toBe('Boolean');
+    });
+  });
+
+  describe('Date/Time types', () => {
+    it('generates Date parameter', () => {
+      const param = p.date();
+      expect(param._tinybirdType).toBe('Date');
+    });
+
+    it('generates DateTime parameter', () => {
+      const param = p.dateTime();
+      expect(param._tinybirdType).toBe('DateTime');
+    });
+
+    it('generates DateTime64 parameter', () => {
+      const param = p.dateTime64();
+      expect(param._tinybirdType).toBe('DateTime64');
+    });
+  });
+
+  describe('Special types', () => {
+    it('generates column parameter', () => {
+      const param = p.column();
+      expect(param._tinybirdType).toBe('column');
+    });
+  });
+
+  describe('Required by default', () => {
+    it('parameters are required by default', () => {
+      const param = p.string();
+      expect(param._required).toBe(true);
+    });
+  });
+
+  describe('Optional modifier', () => {
+    it('makes parameter optional without default', () => {
+      const param = p.int32().optional();
+      expect(param._required).toBe(false);
+      expect(param._default).toBeUndefined();
+    });
+
+    it('makes parameter optional with default value', () => {
+      const param = p.int32().optional(10);
+      expect(param._required).toBe(false);
+      expect(param._default).toBe(10);
+    });
+
+    it('preserves type when optional', () => {
+      const param = p.string().optional('default');
+      expect(param._tinybirdType).toBe('String');
+      expect(param._default).toBe('default');
+    });
+  });
+
+  describe('Required modifier', () => {
+    it('makes optional parameter required again', () => {
+      const param = p.int32().optional(10).required();
+      expect(param._required).toBe(true);
+    });
+  });
+
+  describe('Description modifier', () => {
+    it('sets description', () => {
+      const param = p.string().describe('User ID');
+      expect(param._description).toBe('User ID');
+    });
+
+    it('preserves description when chaining', () => {
+      const param = p.int32().describe('Limit value').optional(10);
+      expect(param._description).toBe('Limit value');
+    });
+  });
+
+  describe('Combined modifiers', () => {
+    it('supports optional with description', () => {
+      const param = p.int32().optional(10).describe('Limit');
+      expect(param._required).toBe(false);
+      expect(param._default).toBe(10);
+      expect(param._description).toBe('Limit');
+    });
+
+    it('supports description then optional', () => {
+      const param = p.int32().describe('Limit').optional(10);
+      expect(param._required).toBe(false);
+      expect(param._default).toBe(10);
+      expect(param._description).toBe('Limit');
+    });
+  });
+
+  describe('Helper functions', () => {
+    it('isParamValidator returns true for validators', () => {
+      expect(isParamValidator(p.string())).toBe(true);
+    });
+
+    it('isParamValidator returns false for non-validators', () => {
+      expect(isParamValidator('string')).toBe(false);
+      expect(isParamValidator({})).toBe(false);
+      expect(isParamValidator(null)).toBe(false);
+    });
+
+    it('getParamTinybirdType returns type string', () => {
+      expect(getParamTinybirdType(p.string())).toBe('String');
+    });
+
+    it('isParamRequired returns required status', () => {
+      expect(isParamRequired(p.string())).toBe(true);
+      expect(isParamRequired(p.string().optional())).toBe(false);
+    });
+
+    it('getParamDefault returns default value', () => {
+      expect(getParamDefault(p.int32().optional(10))).toBe(10);
+      expect(getParamDefault(p.int32())).toBeUndefined();
+    });
+
+    it('getParamDescription returns description', () => {
+      expect(getParamDescription(p.string().describe('Test'))).toBe('Test');
+      expect(getParamDescription(p.string())).toBeUndefined();
+    });
+  });
+
+  describe('Array parameter', () => {
+    it('creates array parameter', () => {
+      const param = p.array(p.string());
+      expect(param._tinybirdType).toBe('Array');
+    });
+  });
+
+  describe('JSON parameter', () => {
+    it('creates JSON parameter', () => {
+      const param = p.json();
+      expect(param._tinybirdType).toBe('JSON');
+    });
+  });
+});

package/src/schema/params.ts

@@ -0,0 +1,249 @@
+/**
+ * Parameter validators for Tinybird pipe queries
+ * Similar to the column type validators but for query parameters
+ */
+
+// Symbol for brand typing
+const PARAM_BRAND = Symbol("tinybird.param");
+
+/**
+ * Base interface for parameter validators
+ */
+export interface ParamValidator<
+  TType,
+  TTinybirdType extends string = string,
+  TRequired extends boolean = true
+> {
+  readonly [PARAM_BRAND]: true;
+  /** The inferred TypeScript type */
+  readonly _type: TType;
+  /** The Tinybird type string for the parameter */
+  readonly _tinybirdType: TTinybirdType;
+  /** Whether this parameter is required */
+  readonly _required: TRequired;
+  /** Default value if optional */
+  readonly _default?: TType;
+  /** Description for documentation */
+  readonly _description?: string;
+
+  /** Make this parameter optional with an optional default value */
+  optional<TDefault extends TType | undefined = undefined>(
+    defaultValue?: TDefault
+  ): ParamValidator<
+    TDefault extends undefined ? TType | undefined : TType,
+    TTinybirdType,
+    false
+  >;
+
+  /** Make this parameter required (default) */
+  required(): ParamValidator<TType, TTinybirdType, true>;
+
+  /** Add a description for this parameter */
+  describe(description: string): ParamValidator<TType, TTinybirdType, TRequired>;
+}
+
+// Internal implementation
+interface ParamValidatorImpl<TType, TTinybirdType extends string, TRequired extends boolean>
+  extends ParamValidator<TType, TTinybirdType, TRequired> {
+  readonly tinybirdType: TTinybirdType;
+  readonly isRequired: TRequired;
+  readonly defaultValue?: TType;
+  readonly description?: string;
+}
+
+function createParamValidator<
+  TType,
+  TTinybirdType extends string,
+  TRequired extends boolean = true
+>(
+  tinybirdType: TTinybirdType,
+  options: {
+    required?: TRequired;
+    defaultValue?: TType;
+    description?: string;
+  } = {}
+): ParamValidator<TType, TTinybirdType, TRequired> {
+  const isRequired = (options.required ?? true) as TRequired;
+
+  const validator: ParamValidatorImpl<TType, TTinybirdType, TRequired> = {
+    [PARAM_BRAND]: true,
+    _type: undefined as unknown as TType,
+    _tinybirdType: tinybirdType,
+    _required: isRequired,
+    _default: options.defaultValue,
+    _description: options.description,
+    tinybirdType,
+    isRequired,
+    defaultValue: options.defaultValue,
+    description: options.description,
+
+    optional<TDefault extends TType | undefined = undefined>(defaultValue?: TDefault) {
+      return createParamValidator<
+        TDefault extends undefined ? TType | undefined : TType,
+        TTinybirdType,
+        false
+      >(tinybirdType, {
+        required: false,
+        defaultValue: defaultValue as TDefault extends undefined ? TType | undefined : TType,
+        description: options.description,
+      });
+    },
+
+    required() {
+      return createParamValidator<TType, TTinybirdType, true>(tinybirdType, {
+        required: true,
+        description: options.description,
+      });
+    },
+
+    describe(description: string) {
+      return createParamValidator<TType, TTinybirdType, TRequired>(tinybirdType, {
+        required: isRequired,
+        defaultValue: options.defaultValue,
+        description,
+      });
+    },
+  };
+
+  return validator;
+}
+
+/**
+ * Parameter validators for Tinybird pipe queries
+ *
+ * @example
+ * ```ts
+ * import { p } from '@tinybirdco/sdk';
+ *
+ * const params = {
+ *   user_id: p.string(),
+ *   limit: p.int32().optional(10),
+ *   start_date: p.dateTime().describe('Start of date range'),
+ * };
+ * ```
+ */
+export const p = {
+  // ============ String Types ============
+
+  /** String parameter */
+  string: () => createParamValidator<string, "String">("String"),
+
+  /** UUID parameter */
+  uuid: () => createParamValidator<string, "UUID">("UUID"),
+
+  // ============ Integer Types ============
+
+  /** Int8 parameter */
+  int8: () => createParamValidator<number, "Int8">("Int8"),
+
+  /** Int16 parameter */
+  int16: () => createParamValidator<number, "Int16">("Int16"),
+
+  /** Int32 parameter */
+  int32: () => createParamValidator<number, "Int32">("Int32"),
+
+  /** Int64 parameter */
+  int64: () => createParamValidator<number, "Int64">("Int64"),
+
+  /** UInt8 parameter */
+  uint8: () => createParamValidator<number, "UInt8">("UInt8"),
+
+  /** UInt16 parameter */
+  uint16: () => createParamValidator<number, "UInt16">("UInt16"),
+
+  /** UInt32 parameter */
+  uint32: () => createParamValidator<number, "UInt32">("UInt32"),
+
+  /** UInt64 parameter */
+  uint64: () => createParamValidator<number, "UInt64">("UInt64"),
+
+  // ============ Float Types ============
+
+  /** Float32 parameter */
+  float32: () => createParamValidator<number, "Float32">("Float32"),
+
+  /** Float64 parameter */
+  float64: () => createParamValidator<number, "Float64">("Float64"),
+
+  // ============ Boolean ============
+
+  /** Boolean parameter */
+  boolean: () => createParamValidator<boolean, "Boolean">("Boolean"),
+
+  // ============ Date/Time Types ============
+
+  /** Date parameter (YYYY-MM-DD format) */
+  date: () => createParamValidator<string, "Date">("Date"),
+
+  /** DateTime parameter (YYYY-MM-DD HH:MM:SS format) */
+  dateTime: () => createParamValidator<string, "DateTime">("DateTime"),
+
+  /** DateTime64 parameter with sub-second precision */
+  dateTime64: () => createParamValidator<string, "DateTime64">("DateTime64"),
+
+  // ============ Array Types ============
+
+  /**
+   * Array parameter - values can be passed as comma-separated or repeated params
+   * @param _element - The type of array elements (used for type inference)
+   * @param _separator - Optional custom separator (default: comma)
+   */
+  array: <TElement extends ParamValidator<unknown, string, boolean>>(
+    _element: TElement,
+    _separator?: string
+  ): ParamValidator<TElement["_type"][], "Array", true> =>
+    createParamValidator<TElement["_type"][], "Array">("Array", {
+      required: true,
+    }),
+
+  // ============ Special Types ============
+
+  /**
+   * Column reference parameter - allows dynamic column selection
+   * Use with caution as it can affect query safety
+   */
+  column: () => createParamValidator<string, "column">("column"),
+
+  /**
+   * JSON parameter - for passing complex structured data
+   */
+  json: <TShape = unknown>() => createParamValidator<TShape, "JSON">("JSON"),
+} as const;
+
+/** Type alias for any parameter validator */
+export type AnyParamValidator = ParamValidator<unknown, string, boolean>;
+
+/** Extract the TypeScript type from a parameter validator */
+export type InferParamType<T extends AnyParamValidator> = T["_required"] extends true
+  ? T["_type"]
+  : T["_type"] | undefined;
+
+/** Check if a value is a parameter validator */
+export function isParamValidator(value: unknown): value is AnyParamValidator {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    PARAM_BRAND in value &&
+    (value as Record<symbol, unknown>)[PARAM_BRAND] === true
+  );
+}
+
+/** Get the Tinybird type string from a parameter validator */
+export function getParamTinybirdType(validator: AnyParamValidator): string {
+  return validator._tinybirdType;
+}
+
+/** Check if a parameter is required */
+export function isParamRequired(validator: AnyParamValidator): boolean {
+  return validator._required;
+}
+
+/** Get the default value of a parameter */
+export function getParamDefault<T>(validator: ParamValidator<T, string, boolean>): T | undefined {
+  return validator._default;
+}
+
+/** Get the description of a parameter */
+export function getParamDescription(validator: AnyParamValidator): string | undefined {
+  return validator._description;
+}