tplm-lang 0.2.6 → 0.3.0

package/README.md

@@ -40,9 +40,19 @@ The original TPL was a language developed by the U.S. Bureau of Labor Statistics
 ## Installation
 
 ```bash
-npm install tplm-lang
+# DuckDB (local CSV, Parquet files)
+npm install tplm-lang @malloydata/db-duckdb
+
+# BigQuery
+npm install tplm-lang @malloydata/db-bigquery
+
+# Both backends
+npm install tplm-lang @malloydata/db-duckdb @malloydata/db-bigquery
 ```
 
+Database backends are **optional peer dependencies** — install only the one(s) you need.
+If you only need parsing and compilation (no query execution), `npm install tplm-lang` alone is sufficient.
+
 ## Quick Start - Query Your Data Immediately
 
 For basic use, no Malloy knowledge is required; just use your local data and start querying.

package/dist/executor/index.d.ts

@@ -2,9 +2,14 @@
  * TPL Executor
  *
  * Executes Malloy queries against BigQuery or DuckDB (local mode) and returns results.
+ *
+ * Database backends are loaded lazily via dynamic imports, so consumers only need
+ * to install the backend(s) they actually use:
+ *   npm install @malloydata/db-duckdb    # for DuckDB support
+ *   npm install @malloydata/db-bigquery  # for BigQuery support
  */
-import { BigQueryConnection } from '@malloydata/db-bigquery';
-import { DuckDBConnection } from '@malloydata/db-duckdb';
+import type { DuckDBConnection } from '@malloydata/db-duckdb';
+import type { BigQueryConnection } from '@malloydata/db-bigquery';
 import { Runtime, Connection } from '@malloydata/malloy';
 export type ConnectionType = 'bigquery' | 'duckdb';
 export interface BigQueryConnectionOptions {
@@ -24,20 +29,26 @@ export interface DuckDBConnectionOptions {
     }[];
 }
 export type ConnectionOptions = BigQueryConnectionOptions | DuckDBConnectionOptions;
-export declare function createConnection(options: ConnectionOptions): Connection;
+/**
+ * Store connection options for deferred creation.
+ * The connection will be created lazily on first getConnection() call.
+ */
+export declare function setPendingConnection(options: ConnectionOptions): void;
+export declare function createConnection(options: ConnectionOptions): Promise<Connection>;
 /**
  * Create a default local DuckDB connection with test data
  */
-export declare function createLocalConnection(): DuckDBConnection;
+export declare function createLocalConnection(): Promise<Connection>;
 /**
  * Get the current connection or create default connection.
  *
  * Connection priority:
  * 1. If connection already exists, return it
- * 2. If TPL_BIGQUERY=true env var is set and credentials exist, use BigQuery
- * 3. Otherwise, use DuckDB (default)
+ * 2. If pending options were set (via setPendingConnection), use those
+ * 3. If TPL_BIGQUERY=true env var is set and credentials exist, use BigQuery
+ * 4. Otherwise, use DuckDB (default)
  */
-export declare function getConnection(): Connection;
+export declare function getConnection(): Promise<Connection>;
 export declare function getConnectionType(): ConnectionType | null;
 export declare function listDatasets(): Promise<string[]>;
 export declare function listTables(dataset: string): Promise<{
@@ -68,4 +79,5 @@ export declare function executeMalloy(malloySource: string, options?: ExecuteOpt
  * Execute raw SQL against the current connection
  */
 export declare function executeSQL(sql: string): Promise<any[]>;
-export { BigQueryConnection, DuckDBConnection, Runtime };
+export { Runtime };
+export type { DuckDBConnection, BigQueryConnection };

package/dist/executor/index.js

@@ -2,9 +2,12 @@
  * TPL Executor
  *
  * Executes Malloy queries against BigQuery or DuckDB (local mode) and returns results.
+ *
+ * Database backends are loaded lazily via dynamic imports, so consumers only need
+ * to install the backend(s) they actually use:
+ *   npm install @malloydata/db-duckdb    # for DuckDB support
+ *   npm install @malloydata/db-bigquery  # for BigQuery support
  */
-import { BigQueryConnection } from '@malloydata/db-bigquery';
-import { DuckDBConnection } from '@malloydata/db-duckdb';
 import { Runtime } from '@malloydata/malloy';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -12,11 +15,49 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
 // ---
+// LAZY MODULE LOADERS
+// ---
+let _DuckDBModule = null;
+let _BigQueryModule = null;
+async function loadDuckDB() {
+    if (!_DuckDBModule) {
+        try {
+            _DuckDBModule = await import('@malloydata/db-duckdb');
+        }
+        catch {
+            throw new Error('@malloydata/db-duckdb is required for DuckDB support. Install it with: npm install @malloydata/db-duckdb');
+        }
+    }
+    return _DuckDBModule;
+}
+async function loadBigQuery() {
+    if (!_BigQueryModule) {
+        try {
+            _BigQueryModule = await import('@malloydata/db-bigquery');
+        }
+        catch {
+            throw new Error('@malloydata/db-bigquery is required for BigQuery support. Install it with: npm install @malloydata/db-bigquery');
+        }
+    }
+    return _BigQueryModule;
+}
+// ---
 // CONNECTION SETUP
 // ---
 let connectionInstance = null;
 let currentConnectionType = null;
-export function createConnection(options) {
+let pendingOptions = null;
+/**
+ * Store connection options for deferred creation.
+ * The connection will be created lazily on first getConnection() call.
+ */
+export function setPendingConnection(options) {
+    pendingOptions = options;
+    // Clear any existing connection so the new options take effect
+    connectionInstance = null;
+    currentConnectionType = null;
+}
+export async function createConnection(options) {
     if (options.type === 'bigquery') {
         return createBigQueryConnection(options);
     }
@@ -24,7 +65,8 @@ export function createConnection(options) {
         return createDuckDBConnection(options);
     }
 }
-function createBigQueryConnection(options) {
+async function createBigQueryConnection(options) {
+    const { BigQueryConnection } = await loadBigQuery();
     const credentialsPath = options.credentialsPath ?? './config/dev-credentials.json';
     // Read credentials to get project ID if not provided
     const credentials = JSON.parse(fs.readFileSync(credentialsPath, 'utf-8'));
@@ -36,7 +78,8 @@ function createBigQueryConnection(options) {
     currentConnectionType = 'bigquery';
     return connection;
 }
-function createDuckDBConnection(options) {
+async function createDuckDBConnection(options) {
+    const { DuckDBConnection } = await loadDuckDB();
     const connection = new DuckDBConnection('duckdb', options.databasePath ?? ':memory:', undefined);
     connectionInstance = connection;
     currentConnectionType = 'duckdb';
@@ -45,7 +88,7 @@ function createDuckDBConnection(options) {
 /**
  * Create a default local DuckDB connection with test data
  */
-export function createLocalConnection() {
+export async function createLocalConnection() {
     return createDuckDBConnection({
         type: 'duckdb',
     });
@@ -55,37 +98,48 @@ export function createLocalConnection() {
  *
  * Connection priority:
  * 1. If connection already exists, return it
- * 2. If TPL_BIGQUERY=true env var is set and credentials exist, use BigQuery
- * 3. Otherwise, use DuckDB (default)
+ * 2. If pending options were set (via setPendingConnection), use those
+ * 3. If TPL_BIGQUERY=true env var is set and credentials exist, use BigQuery
+ * 4. Otherwise, use DuckDB (default)
  */
-export function getConnection() {
+export async function getConnection() {
     if (!connectionInstance) {
+        // Use pending options if set
+        if (pendingOptions) {
+            const opts = pendingOptions;
+            pendingOptions = null;
+            return await createConnection(opts);
+        }
         // BigQuery only if explicitly requested via env var AND credentials exist
         const useBigQuery = process.env.TPL_BIGQUERY === 'true';
         const credentialsPath = './config/dev-credentials.json';
         if (useBigQuery && fs.existsSync(credentialsPath)) {
             try {
-                return createConnection({ type: 'bigquery', credentialsPath });
+                return await createConnection({ type: 'bigquery', credentialsPath });
             }
             catch (e) {
                 console.log('BigQuery connection failed, falling back to DuckDB');
-                return createLocalConnection();
+                return await createLocalConnection();
             }
         }
         // Default: DuckDB
-        return createLocalConnection();
+        return await createLocalConnection();
     }
     return connectionInstance;
 }
 export function getConnectionType() {
+    // Return pending type if connection hasn't been created yet
+    if (!currentConnectionType && pendingOptions) {
+        return pendingOptions.type;
+    }
     return currentConnectionType;
 }
 // ---
 // SCHEMA EXPLORATION (BigQuery only)
 // ---
 export async function listDatasets() {
-    const conn = getConnection();
-    if (!(conn instanceof BigQueryConnection)) {
+    const conn = await getConnection();
+    if (currentConnectionType !== 'bigquery') {
         throw new Error('listDatasets only supported for BigQuery');
     }
     const result = await conn.runSQL(`
@@ -96,8 +150,8 @@ export async function listDatasets() {
     return result.rows.map((row) => row.schema_name);
 }
 export async function listTables(dataset) {
-    const conn = getConnection();
-    if (!(conn instanceof BigQueryConnection)) {
+    const conn = await getConnection();
+    if (currentConnectionType !== 'bigquery') {
         throw new Error('listTables only supported for BigQuery');
     }
     const result = await conn.runSQL(`
@@ -117,8 +171,8 @@ export async function listTables(dataset) {
     }));
 }
 export async function describeTable(dataset, table) {
-    const conn = getConnection();
-    if (!(conn instanceof BigQueryConnection)) {
+    const conn = await getConnection();
+    if (currentConnectionType !== 'bigquery') {
         throw new Error('describeTable only supported for BigQuery');
     }
     const result = await conn.runSQL(`
@@ -133,8 +187,8 @@ export async function describeTable(dataset, table) {
     }));
 }
 export async function sampleTable(dataset, table, limit = 10) {
-    const conn = getConnection();
-    if (!(conn instanceof BigQueryConnection)) {
+    const conn = await getConnection();
+    if (currentConnectionType !== 'bigquery') {
         throw new Error('sampleTable only supported for BigQuery');
     }
     const result = await conn.runSQL(`
@@ -150,7 +204,7 @@ export async function sampleTable(dataset, table, limit = 10) {
  */
 export function getDefaultSource() {
     const connType = getConnectionType();
-    if (connType === 'duckdb') {
+    if (connType === 'duckdb' || connType === null) {
         const csvPath = path.join(PROJECT_ROOT, 'data/test_usa_names.csv');
         return `
 source: names is duckdb.table('${csvPath}') extend {
@@ -181,7 +235,7 @@ source: names is bigquery.table('slite-development.tpl_test.test_usa_names') ext
  * Execute a Malloy query string
  */
 export async function executeMalloy(malloySource, options = {}) {
-    const conn = getConnection();
+    const conn = await getConnection();
     // Create a minimal URL reader (we're passing source directly)
     const urlReader = {
         readURL: async (url) => {
@@ -215,18 +269,11 @@ export async function executeMalloy(malloySource, options = {}) {
  * Execute raw SQL against the current connection
  */
 export async function executeSQL(sql) {
-    const conn = getConnection();
-    if (conn instanceof BigQueryConnection) {
-        const result = await conn.runSQL(sql);
-        return result.rows;
-    }
-    else if (conn instanceof DuckDBConnection) {
-        const result = await conn.runSQL(sql);
-        return result.rows;
-    }
-    throw new Error('Unknown connection type');
+    const conn = await getConnection();
+    const result = await conn.runSQL(sql);
+    return result.rows;
 }
 // ---
 // EXPORTS
 // ---
-export { BigQueryConnection, DuckDBConnection, Runtime };
+export { Runtime };

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { buildTableSpec, generateQueryPlan, generateMalloyQueries, buildGridSpec
 export type { TableSpec, QueryPlan, GridSpec, HeaderNode, QueryResults, MalloyQuerySpec, } from './compiler/index.js';
 export { renderGridToHTML } from './renderer/index.js';
 export type { GridRenderOptions } from './renderer/index.js';
-export { createConnection, createLocalConnection, getConnection, getConnectionType, getDefaultSource, executeMalloy, executeSQL, } from './executor/index.js';
+export { createConnection, createLocalConnection, getConnection, getConnectionType, getDefaultSource, executeMalloy, executeSQL, setPendingConnection, } from './executor/index.js';
 export type { ConnectionType, ConnectionOptions, BigQueryConnectionOptions, DuckDBConnectionOptions, ExecuteOptions, } from './executor/index.js';
 import type { TableSpec, QueryPlan, GridSpec, MalloyQuerySpec } from './compiler/index.js';
 import type { DimensionOrderingProvider } from './compiler/dimension-utils.js';
@@ -134,10 +134,12 @@ export declare class TPL {
 }
 /**
  * Create a TPL instance with DuckDB connection (simplest way to start).
+ * Connection is created lazily on first execute() call.
  */
 export declare function createTPL(options?: TPLOptions): TPL;
 /**
  * Create a TPL instance with BigQuery connection.
+ * Connection is created lazily on first execute() call.
  */
 export declare function createBigQueryTPL(options?: TPLOptions & {
     credentialsPath?: string;

package/dist/index.js

@@ -34,11 +34,11 @@ export { buildTableSpec, generateQueryPlan, generateMalloyQueries, buildGridSpec
 // renderer
 export { renderGridToHTML } from './renderer/index.js';
 // executor
-export { createConnection, createLocalConnection, getConnection, getConnectionType, getDefaultSource, executeMalloy, executeSQL, } from './executor/index.js';
+export { createConnection, createLocalConnection, getConnection, getConnectionType, getDefaultSource, executeMalloy, executeSQL, setPendingConnection, } from './executor/index.js';
 // --- internal imports ---
 import { parse } from './parser/index.js';
 import { buildTableSpec, generateQueryPlan, generateMalloyQueries, buildGridSpec } from './compiler/index.js';
-import { executeMalloy, createConnection, createLocalConnection, } from './executor/index.js';
+import { executeMalloy, setPendingConnection, } from './executor/index.js';
 import { renderGridToHTML } from './renderer/index.js';
 /**
  * High-level TPL API for parsing, compiling, executing, and rendering.
@@ -102,16 +102,18 @@ export class TPL {
 }
 /**
  * Create a TPL instance with DuckDB connection (simplest way to start).
+ * Connection is created lazily on first execute() call.
  */
 export function createTPL(options = {}) {
-    createLocalConnection();
+    setPendingConnection({ type: 'duckdb' });
     return new TPL(options);
 }
 /**
  * Create a TPL instance with BigQuery connection.
+ * Connection is created lazily on first execute() call.
  */
 export function createBigQueryTPL(options = {}) {
-    createConnection({
+    setPendingConnection({
         type: 'bigquery',
         credentialsPath: options.credentialsPath,
         projectId: options.projectId,
@@ -134,7 +136,7 @@ import { analyzeAndGeneratePercentileConfig, postProcessMalloyForPercentiles, ge
  * ```
  */
 export function fromDuckDBTable(tablePath, options = {}) {
-    createLocalConnection();
+    setPendingConnection({ type: 'duckdb' });
     const sourceName = 'data';
     const model = `source: ${sourceName} is duckdb.table('${tablePath}')`;
     return new EasyTPL(model, sourceName, {
@@ -170,7 +172,7 @@ export function fromCSV(csvPath, options = {}) {
  * ```
  */
 export function fromBigQueryTable(options) {
-    createConnection({
+    setPendingConnection({
         type: 'bigquery',
         credentialsPath: options.credentialsPath,
         projectId: options.projectId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tplm-lang",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "TPLm - Table Producing Language backed by Malloy.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,17 +29,29 @@
     "docs:preview": "cd docs-site && npm run docs:preview"
   },
   "devDependencies": {
+    "@malloydata/db-bigquery": "^0.0.326",
+    "@malloydata/db-duckdb": "^0.0.326",
     "@types/node": "^20.0.0",
     "peggy": "^4.0.0",
     "typescript": "^5.0.0",
     "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@malloydata/db-bigquery": "^0.0.326",
-    "@malloydata/db-duckdb": "^0.0.326",
     "@malloydata/malloy": "^0.0.326",
     "chevrotain": "^11.0.3"
   },
+  "peerDependencies": {
+    "@malloydata/db-bigquery": "^0.0.326",
+    "@malloydata/db-duckdb": "^0.0.326"
+  },
+  "peerDependenciesMeta": {
+    "@malloydata/db-bigquery": {
+      "optional": true
+    },
+    "@malloydata/db-duckdb": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18.0.0"
   },