@tinybirdco/sdk 0.0.30 → 0.0.31

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({

package/src/client/base.ts

@@ -130,9 +130,11 @@ export class TinybirdClient {
     try {
       // Dynamic import to avoid circular dependencies and to keep CLI code
       // out of the client bundle when not using dev mode
-      const { loadConfig } = await import("../cli/config.js");
+      const { loadConfigAsync } = await import("../cli/config.js");
       const { getOrCreateBranch } = await import("../api/branches.js");
-      const { isPreviewEnvironment, getPreviewBranchName } = await import("./preview.js");
+      const { isPreviewEnvironment, getPreviewBranchName } = await import(
+        "./preview.js"
+      );
 
       // In preview environments (Vercel preview, CI), the token was already resolved
       // by resolveToken() in project.ts - skip branch creation to avoid conflicts
@@ -140,9 +142,14 @@ export class TinybirdClient {
         const gitBranchName = getPreviewBranchName();
         // Preview branches use the tmp_ci_ prefix (matches what tinybird preview creates)
         const sanitized = gitBranchName
-          ? gitBranchName.replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "")
+          ? gitBranchName
+              .replace(/[^a-zA-Z0-9_]/g, "_")
+              .replace(/_+/g, "_")
+              .replace(/^_|_$/g, "")
+          : undefined;
+        const tinybirdBranchName = sanitized
+          ? `tmp_ci_${sanitized}`
           : undefined;
-        const tinybirdBranchName = sanitized ? `tmp_ci_${sanitized}` : undefined;
         return this.buildContext({
           token: this.config.token,
           isBranchToken: !!tinybirdBranchName,
@@ -153,12 +160,16 @@ export class TinybirdClient {
 
       // Use configDir if provided (important for monorepo setups where process.cwd()
       // may not be in the same directory tree as tinybird.json)
-      const config = loadConfig(this.config.configDir);
+      const config = await loadConfigAsync(this.config.configDir);
       const gitBranch = config.gitBranch ?? undefined;
 
       // If on main branch, use the workspace token
       if (config.isMainBranch || !config.tinybirdBranch) {
-        return this.buildContext({ token: this.config.token, isBranchToken: false, gitBranch });
+        return this.buildContext({
+          token: this.config.token,
+          isBranchToken: false,
+          gitBranch,
+        });
       }
 
       const branchName = config.tinybirdBranch;
@@ -171,7 +182,11 @@ export class TinybirdClient {
 
       if (!branch.token) {
         // Fall back to workspace token if no branch token
-        return this.buildContext({ token: this.config.token, isBranchToken: false, gitBranch });
+        return this.buildContext({
+          token: this.config.token,
+          isBranchToken: false,
+          gitBranch,
+        });
       }
 
       return this.buildContext({
@@ -180,9 +195,11 @@ export class TinybirdClient {
         branchName,
         gitBranch,
       });
-    } catch {
-      // If anything fails, fall back to the workspace token
-      return this.buildContext({ token: this.config.token, isBranchToken: false });
+    } catch (error) {
+      throw new TinybirdError(
+        `Failed to resolve branch context: ${(error as Error).message}`,
+        500
+      );
     }
   }
 
@@ -240,7 +257,11 @@ export class TinybirdClient {
     const token = await this.getToken();
 
     try {
-      return await this.getApi(token).ingestBatch(datasourceName, events, options);
+      return await this.getApi(token).ingestBatch(
+        datasourceName,
+        events,
+        options
+      );
     } catch (error) {
       this.rethrowApiError(error);
     }
@@ -310,11 +331,7 @@ export class TinybirdClient {
 
   private rethrowApiError(error: unknown): never {
     if (error instanceof TinybirdApiError) {
-      throw new TinybirdError(
-        error.message,
-        error.statusCode,
-        error.response
-      );
+      throw new TinybirdError(error.message, error.statusCode, error.response);
     }
 
     throw error;

package/src/index.ts

@@ -245,3 +245,7 @@ export {
   getLocalDashboardUrl,
 } from "./api/dashboard.js";
 export type { RegionInfo } from "./api/dashboard.js";
+
+// ============ Config Types ============
+// Import from config-types.ts to avoid bundling esbuild in client code
+export type { TinybirdConfig, DevMode } from "./cli/config-types.js";