@tinybirdco/sdk 0.0.30 → 0.0.32

package/src/cli/config-loader.ts

@@ -0,0 +1,87 @@
+/**
+ * Universal config file loader
+ * Supports .json, .cjs, and .mjs files
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type LoadedConfig<T> = {
+  config: T;
+  filepath: string;
+};
+
+export type LoadConfigOptions = {
+  cwd?: string;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readJsonFile<T>(filepath: string): Promise<T> {
+  const raw = await fs.readFile(filepath, "utf8");
+  return JSON.parse(raw) as T;
+}
+
+/**
+ * Resolve the config export from a module
+ * Supports default export, module.exports, and function configs
+ */
+async function resolveConfigExport(mod: unknown): Promise<unknown> {
+  const moduleObj = mod as Record<string, unknown>;
+  const exported = moduleObj?.default ?? mod;
+
+  // Allow config as function (sync/async)
+  if (typeof exported === "function") {
+    return await (exported as () => MaybePromise<unknown>)();
+  }
+  return exported;
+}
+
+/**
+ * Load a config file from disk
+ * Supports .json, .cjs, and .mjs files
+ */
+export async function loadConfigFile<T = unknown>(
+  configPath: string,
+  opts: LoadConfigOptions = {}
+): Promise<LoadedConfig<T>> {
+  const cwd = opts.cwd ?? process.cwd();
+  const filepath = path.isAbsolute(configPath)
+    ? configPath
+    : path.resolve(cwd, configPath);
+
+  const ext = path.extname(filepath).toLowerCase();
+
+  if (ext === ".json") {
+    const config = await readJsonFile<T>(filepath);
+    return { config, filepath };
+  }
+
+  if (ext === ".mjs" || ext === ".cjs") {
+    // Load JS modules via runtime import for bundler compatibility
+    const url = pathToFileURL(filepath).href;
+    const mod = await import(
+      /* webpackIgnore: true */
+      /* @vite-ignore */
+      url
+    );
+    const config = await resolveConfigExport(mod);
+
+    if (!isObject(config)) {
+      throw new Error(
+        `Config in ${filepath} must export an object (or a function returning an object).`
+      );
+    }
+
+    return { config: config as T, filepath };
+  }
+
+  throw new Error(
+    `Unsupported config extension "${ext}". Use .json, .mjs, or .cjs`
+  );
+}

package/src/cli/config-types.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration types for tinybird.config.{ts,js,json}
+ *
+ * This file is separate from config.ts to avoid pulling in esbuild
+ * when these types are imported by client code.
+ */
+
+/**
+ * Development mode options
+ * - "branch": Use Tinybird cloud with branches (default)
+ * - "local": Use local Tinybird container at localhost:7181
+ */
+export type DevMode = "branch" | "local";
+
+/**
+ * Tinybird configuration file structure
+ */
+export interface TinybirdConfig {
+  /** Array of TypeScript files to scan for datasources and pipes */
+  include?: string[];
+  /** @deprecated Use `include` instead. Path to the TypeScript schema entry point */
+  schema?: string;
+  /** API token (supports ${ENV_VAR} interpolation) */
+  token: string;
+  /** Tinybird API base URL (optional, defaults to EU region) */
+  baseUrl?: string;
+  /** Development mode: "branch" (default) or "local" */
+  devMode?: DevMode;
+}

package/src/cli/config.test.ts

@@ -8,6 +8,7 @@ import {
   getRelativeTinybirdDir,
   findConfigFile,
   loadConfig,
+  loadConfigAsync,
   getConfigPath,
   configExists,
   updateConfig,
@@ -73,20 +74,60 @@ describe("Config", () => {
   });
 
   describe("findConfigFile", () => {
-    it("finds tinybird.json in current directory", () => {
+    it("finds tinybird.config.json in current directory", () => {
+      const configPath = path.join(tempDir, "tinybird.config.json");
+      fs.writeFileSync(configPath, "{}");
+
+      const result = findConfigFile(tempDir);
+      expect(result).not.toBe(null);
+      expect(result?.path).toBe(configPath);
+      expect(result?.type).toBe("tinybird.config.json");
+    });
+
+    it("finds tinybird.json in current directory (legacy)", () => {
       const configPath = path.join(tempDir, "tinybird.json");
       fs.writeFileSync(configPath, "{}");
 
-      expect(findConfigFile(tempDir)).toBe(configPath);
+      const result = findConfigFile(tempDir);
+      expect(result).not.toBe(null);
+      expect(result?.path).toBe(configPath);
+      expect(result?.type).toBe("tinybird.json");
     });
 
-    it("finds tinybird.json in parent directory", () => {
+    it("finds tinybird.config.json in parent directory", () => {
       const nestedDir = path.join(tempDir, "src", "app");
       fs.mkdirSync(nestedDir, { recursive: true });
-      const configPath = path.join(tempDir, "tinybird.json");
+      const configPath = path.join(tempDir, "tinybird.config.json");
       fs.writeFileSync(configPath, "{}");
 
-      expect(findConfigFile(nestedDir)).toBe(configPath);
+      const result = findConfigFile(nestedDir);
+      expect(result).not.toBe(null);
+      expect(result?.path).toBe(configPath);
+      expect(result?.type).toBe("tinybird.config.json");
+    });
+
+    it("prioritizes tinybird.config.json over tinybird.json", () => {
+      const newConfig = path.join(tempDir, "tinybird.config.json");
+      const legacyConfig = path.join(tempDir, "tinybird.json");
+      fs.writeFileSync(newConfig, "{}");
+      fs.writeFileSync(legacyConfig, "{}");
+
+      const result = findConfigFile(tempDir);
+      expect(result).not.toBe(null);
+      expect(result?.path).toBe(newConfig);
+      expect(result?.type).toBe("tinybird.config.json");
+    });
+
+    it("prioritizes tinybird.config.mjs over tinybird.config.cjs", () => {
+      const mjsConfig = path.join(tempDir, "tinybird.config.mjs");
+      const cjsConfig = path.join(tempDir, "tinybird.config.cjs");
+      fs.writeFileSync(mjsConfig, "export default {};");
+      fs.writeFileSync(cjsConfig, "module.exports = {};");
+
+      const result = findConfigFile(tempDir);
+      expect(result).not.toBe(null);
+      expect(result?.path).toBe(mjsConfig);
+      expect(result?.type).toBe("tinybird.config.mjs");
     });
 
     it("returns null when no config file exists", () => {
@@ -95,8 +136,10 @@ describe("Config", () => {
   });
 
   describe("getConfigPath", () => {
-    it("returns path to tinybird.json in directory", () => {
-      expect(getConfigPath(tempDir)).toBe(path.join(tempDir, "tinybird.json"));
+    it("returns path to tinybird.config.json (new default) in directory", () => {
+      expect(getConfigPath(tempDir)).toBe(
+        path.join(tempDir, "tinybird.config.json")
+      );
     });
   });
 
@@ -123,7 +166,7 @@ describe("Config", () => {
     });
 
     it("throws error when no config file exists", () => {
-      expect(() => loadConfig(tempDir)).toThrow("Could not find tinybird.json");
+      expect(() => loadConfig(tempDir)).toThrow("Could not find config file");
     });
 
     it("loads config with include array", () => {
@@ -286,6 +329,50 @@ describe("Config", () => {
     });
   });
 
+  describe("loadConfigAsync", () => {
+    beforeEach(() => {
+      // Mock git functions to avoid git dependency in tests
+      vi.mock("./git.js", () => ({
+        getCurrentGitBranch: () => "main",
+        isMainBranch: () => true,
+        getTinybirdBranchName: () => null,
+      }));
+    });
+
+    it("loads tinybird.config.mjs", async () => {
+      fs.writeFileSync(
+        path.join(tempDir, "tinybird.config.mjs"),
+        `export default {
+  include: ["lib/datasources.ts"],
+  token: "test-token"
+};`
+      );
+
+      const result = await loadConfigAsync(tempDir);
+
+      expect(result.include).toEqual(["lib/datasources.ts"]);
+      expect(result.token).toBe("test-token");
+      expect(result.baseUrl).toBe("https://api.tinybird.co");
+    });
+
+    it("loads tinybird.config.cjs", async () => {
+      fs.writeFileSync(
+        path.join(tempDir, "tinybird.config.cjs"),
+        `module.exports = {
+  include: ["lib/datasources.ts"],
+  token: "test-token"
+};`
+      );
+
+      const result = await loadConfigAsync(tempDir);
+
+      expect(result.include).toEqual(["lib/datasources.ts"]);
+      expect(result.token).toBe("test-token");
+      expect(result.baseUrl).toBe("https://api.tinybird.co");
+    });
+
+  });
+
   describe("updateConfig", () => {
     it("updates existing config file", () => {
       const configPath = path.join(tempDir, "tinybird.json");

package/src/cli/config.ts

@@ -6,28 +6,9 @@ import * as fs from "fs";
 import * as path from "path";
 import { getCurrentGitBranch, isMainBranch, getTinybirdBranchName } from "./git.js";
 
-/**
- * Development mode options
- * - "branch": Use Tinybird cloud with branches (default)
- * - "local": Use local Tinybird container at localhost:7181
- */
-export type DevMode = "branch" | "local";
-
-/**
- * Tinybird configuration file structure
- */
-export interface TinybirdConfig {
-  /** Array of TypeScript files to scan for datasources and pipes */
-  include?: string[];
-  /** @deprecated Use `include` instead. Path to the TypeScript schema entry point */
-  schema?: string;
-  /** API token (supports ${ENV_VAR} interpolation) */
-  token: string;
-  /** Tinybird API base URL (optional, defaults to EU region) */
-  baseUrl?: string;
-  /** Development mode: "branch" (default) or "local" */
-  devMode?: DevMode;
-}
+// Re-export types from config-types.ts (separate file to avoid bundling esbuild)
+export type { DevMode, TinybirdConfig } from "./config-types.js";
+import type { DevMode, TinybirdConfig } from "./config-types.js";
 
 /**
  * Resolved configuration with all values expanded
@@ -64,9 +45,25 @@ const DEFAULT_BASE_URL = "https://api.tinybird.co";
 export const LOCAL_BASE_URL = "http://localhost:7181";
 
 /**
- * Config file name
+ * Config file names in priority order
+ * - tinybird.config.mjs: ESM config with dynamic logic
+ * - tinybird.config.cjs: CommonJS config with dynamic logic
+ * - tinybird.config.json: Standard JSON config (default for new projects)
+ * - tinybird.json: Legacy JSON config (backward compatible)
  */
-const CONFIG_FILE = "tinybird.json";
+const CONFIG_FILES = [
+  "tinybird.config.mjs",
+  "tinybird.config.cjs",
+  "tinybird.config.json",
+  "tinybird.json",
+] as const;
+
+type ConfigFileType = (typeof CONFIG_FILES)[number];
+
+/**
+ * Default config file name for new projects
+ */
+const DEFAULT_CONFIG_FILE = "tinybird.config.json";
 
 /**
  * Tinybird file path within lib folder
@@ -135,19 +132,33 @@ function interpolateEnvVars(value: string): string {
   });
 }
 
+/**
+ * Result of finding a config file
+ */
+export interface ConfigFileResult {
+  /** Full path to the config file */
+  path: string;
+  /** Type of config file found */
+  type: ConfigFileType;
+}
+
 /**
  * Find the config file by walking up the directory tree
+ * Checks for all supported config file names in priority order
  *
  * @param startDir - Directory to start searching from
- * @returns Path to the config file, or null if not found
+ * @returns Path and type of the config file, or null if not found
  */
-export function findConfigFile(startDir: string): string | null {
+export function findConfigFile(startDir: string): ConfigFileResult | null {
   let currentDir = startDir;
 
   while (true) {
-    const configPath = path.join(currentDir, CONFIG_FILE);
-    if (fs.existsSync(configPath)) {
-      return configPath;
+    // Check each config file type in priority order
+    for (const configFile of CONFIG_FILES) {
+      const configPath = path.join(currentDir, configFile);
+      if (fs.existsSync(configPath)) {
+        return { path: configPath, type: configFile };
+      }
     }
 
     const parentDir = path.dirname(currentDir);
@@ -159,42 +170,13 @@ export function findConfigFile(startDir: string): string | null {
   }
 }
 
+// Import the universal config loader
+import { loadConfigFile } from "./config-loader.js";
+
 /**
- * Load and resolve the tinybird.json configuration
- *
- * @param cwd - Working directory to start searching from (defaults to process.cwd())
- * @returns Resolved configuration
- *
- * @example
- * ```ts
- * const config = loadConfig();
- * console.log(config.schema); // 'lib/tinybird.ts' or 'src/lib/tinybird.ts'
- * console.log(config.token);  // 'p.xxx' (resolved from ${TINYBIRD_TOKEN})
- * ```
+ * Resolve a TinybirdConfig to a ResolvedConfig
  */
-export function loadConfig(cwd: string = process.cwd()): ResolvedConfig {
-  const configPath = findConfigFile(cwd);
-
-  if (!configPath) {
-    throw new Error(
-      `Could not find ${CONFIG_FILE}. Run 'npx tinybird init' to create one.`
-    );
-  }
-
-  let rawContent: string;
-  try {
-    rawContent = fs.readFileSync(configPath, "utf-8");
-  } catch (error) {
-    throw new Error(`Failed to read ${configPath}: ${(error as Error).message}`);
-  }
-
-  let config: TinybirdConfig;
-  try {
-    config = JSON.parse(rawContent) as TinybirdConfig;
-  } catch (error) {
-    throw new Error(`Failed to parse ${configPath}: ${(error as Error).message}`);
-  }
-
+function resolveConfig(config: TinybirdConfig, configPath: string): ResolvedConfig {
   // Validate required fields - need either include or schema
   if (!config.include && !config.schema) {
     throw new Error(`Missing 'include' field in ${configPath}. Add an array of files to scan for datasources and pipes.`);
@@ -262,28 +244,140 @@ export function loadConfig(cwd: string = process.cwd()): ResolvedConfig {
 }
 
 /**
- * Check if a config file exists in the given directory
+ * Load and resolve the Tinybird configuration
+ *
+ * Supports the following config file formats (in priority order):
+ * - tinybird.config.mjs: ESM config with dynamic logic
+ * - tinybird.config.cjs: CommonJS config with dynamic logic
+ * - tinybird.config.json: Standard JSON config
+ * - tinybird.json: Legacy JSON config (backward compatible)
+ *
+ * @param cwd - Working directory to start searching from (defaults to process.cwd())
+ * @returns Resolved configuration
+ *
+ * @example
+ * ```ts
+ * const config = loadConfig();
+ * console.log(config.include); // ['lib/tinybird.ts']
+ * console.log(config.token);   // 'p.xxx' (resolved from ${TINYBIRD_TOKEN})
+ * ```
+ */
+export function loadConfig(cwd: string = process.cwd()): ResolvedConfig {
+  const configResult = findConfigFile(cwd);
+
+  if (!configResult) {
+    throw new Error(
+      `Could not find config file. Run 'npx tinybird init' to create one.\n` +
+      `Searched for: ${CONFIG_FILES.join(", ")}`
+    );
+  }
+
+  const { path: configPath, type: configType } = configResult;
+
+  // JSON files can be loaded synchronously
+  if (configType === "tinybird.config.json" || configType === "tinybird.json") {
+    let rawContent: string;
+    try {
+      rawContent = fs.readFileSync(configPath, "utf-8");
+    } catch (error) {
+      throw new Error(`Failed to read ${configPath}: ${(error as Error).message}`);
+    }
+
+    let config: TinybirdConfig;
+    try {
+      config = JSON.parse(rawContent) as TinybirdConfig;
+    } catch (error) {
+      throw new Error(`Failed to parse ${configPath}: ${(error as Error).message}`);
+    }
+
+    return resolveConfig(config, configPath);
+  }
+
+  // For JS files, we need to throw an error asking to use the async version
+  throw new Error(
+    `Config file ${configPath} is a JavaScript file. ` +
+    `Use loadConfigAsync() instead of loadConfig() to load .mjs/.cjs config files.`
+  );
+}
+
+/**
+ * Load and resolve the Tinybird configuration (async version)
+ *
+ * This async version supports all config file formats including JS files
+ * that may contain dynamic logic.
+ *
+ * @param cwd - Working directory to start searching from (defaults to process.cwd())
+ * @returns Promise resolving to the configuration
+ */
+export async function loadConfigAsync(cwd: string = process.cwd()): Promise<ResolvedConfig> {
+  const configResult = findConfigFile(cwd);
+
+  if (!configResult) {
+    throw new Error(
+      `Could not find config file. Run 'npx tinybird init' to create one.\n` +
+      `Searched for: ${CONFIG_FILES.join(", ")}`
+    );
+  }
+
+  const { path: configPath } = configResult;
+
+  // Use the universal config loader for all file types
+  const { config } = await loadConfigFile<TinybirdConfig>(configPath);
+
+  return resolveConfig(config, configPath);
+}
+
+/**
+ * Check if a config file exists in the given directory or its parents
  */
 export function configExists(cwd: string = process.cwd()): boolean {
   return findConfigFile(cwd) !== null;
 }
 
+/**
+ * Get the path to an existing config file, or the default path for a new config
+ * This is useful for the init command which needs to either update an existing config
+ * or create a new one with the new default name
+ */
+export function getExistingOrNewConfigPath(cwd: string = process.cwd()): string {
+  const existing = findExistingConfigPath(cwd);
+  return existing ?? path.join(cwd, DEFAULT_CONFIG_FILE);
+}
+
 /**
  * Get the expected config file path for a directory
+ * Returns the path for the default config file name (tinybird.config.json)
  */
 export function getConfigPath(cwd: string = process.cwd()): string {
-  return path.join(cwd, CONFIG_FILE);
+  return path.join(cwd, DEFAULT_CONFIG_FILE);
+}
+
+/**
+ * Find an existing config file in a directory
+ * Returns the path to the first matching config file, or null if none found
+ */
+export function findExistingConfigPath(cwd: string = process.cwd()): string | null {
+  for (const configFile of CONFIG_FILES) {
+    const configPath = path.join(cwd, configFile);
+    if (fs.existsSync(configPath)) {
+      return configPath;
+    }
+  }
+  return null;
 }
 
 /**
- * Update specific fields in tinybird.json
+ * Update specific fields in a JSON config file
+ *
+ * Note: Only works with JSON config files (.json). For JS config files,
+ * the user needs to update them manually.
  *
  * Throws an error if the config file doesn't exist to prevent creating
  * partial config files that would break loadConfig.
  *
  * @param configPath - Path to the config file
  * @param updates - Fields to update
- * @throws Error if config file doesn't exist
+ * @throws Error if config file doesn't exist or is not a JSON file
  */
 export function updateConfig(
   configPath: string,
@@ -293,6 +387,12 @@ export function updateConfig(
     throw new Error(`Config not found at ${configPath}`);
   }
 
+  if (!configPath.endsWith(".json")) {
+    throw new Error(
+      `Cannot update ${configPath}. Only JSON config files can be updated programmatically.`
+    );
+  }
+
   const content = fs.readFileSync(configPath, "utf-8");
   const config = JSON.parse(content) as TinybirdConfig;
 
@@ -305,17 +405,26 @@ export function updateConfig(
 /**
  * Check if a valid token is configured (either in file or via env var)
  *
+ * Note: For JS config files, this only works if the token is a static value
+ * or environment variable reference in the file.
+ *
  * @param cwd - Working directory to search from
  * @returns true if a valid token exists
  */
 export function hasValidToken(cwd: string = process.cwd()): boolean {
   try {
-    const configPath = findConfigFile(cwd);
-    if (!configPath) {
+    const configResult = findConfigFile(cwd);
+    if (!configResult) {
       return false;
     }
 
-    const content = fs.readFileSync(configPath, "utf-8");
+    // For JS files, we can't easily check without loading them
+    // Return true and let loadConfig handle validation
+    if (!configResult.path.endsWith(".json")) {
+      return true;
+    }
+
+    const content = fs.readFileSync(configResult.path, "utf-8");
     const config = JSON.parse(content) as TinybirdConfig;
 
     if (!config.token) {

package/src/cli/index.ts

@@ -247,6 +247,7 @@ function createCli(): Command {
     .option("--dry-run", "Generate without pushing to API")
     .option("--debug", "Show debug output including API requests/responses")
     .option("--local", "Use local Tinybird container")
+    .option("--branch", "Use Tinybird cloud with branches")
     .action(async (options) => {
       if (options.debug) {
         process.env.TINYBIRD_DEBUG = "1";
@@ -256,6 +257,8 @@ function createCli(): Command {
       let devModeOverride: DevMode | undefined;
       if (options.local) {
         devModeOverride = "local";
+      } else if (options.branch) {
+        devModeOverride = "branch";
       }
 
       const result = await runBuild({