@bayoudhi/moose-lib-serverless 0.3.2 → 0.4.0

package/README.md

@@ -83,7 +83,47 @@ const { OlapTable, Stream, sql } = require("@bayoudhi/moose-lib-serverless");
 import { OlapTable, Stream, sql } from "@bayoudhi/moose-lib-serverless";
 ```
 
-> **Note**: The CJS bundle is recommended for AWS Lambda because ESM top-level imports cannot be lazily deferred. The CJS bundle keeps the Kafka reference inside a lazy `__esm` block that never executes unless you explicitly call `getClickhouseClient()` or `getKafkaProducer()`.
+ > **Note**: The CJS bundle is recommended for AWS Lambda because ESM top-level imports cannot be lazily deferred. The CJS bundle keeps the Kafka reference inside a lazy `__esm` block that never executes unless you explicitly call `getClickhouseClient()` or `getKafkaProducer()`.
+
+## ClickHouse Configuration for Serverless
+
+In a standard Moose project, ClickHouse connection details are read from `moose.config.toml`. This file doesn't exist in serverless environments, so calling `OlapTable.insert()` would throw a `ConfigError`.
+
+Use `configureClickHouse()` to provide connection details programmatically. Call it **once** during cold start, before any `.insert()` calls:
+
+```typescript
+import { configureClickHouse, OlapTable } from "@bayoudhi/moose-lib-serverless";
+
+// Call once at module level (runs during Lambda cold start)
+configureClickHouse({
+  host: process.env.CLICKHOUSE_HOST!,
+  port: process.env.CLICKHOUSE_PORT!,       // string, e.g. "8443"
+  username: process.env.CLICKHOUSE_USER!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  database: process.env.CLICKHOUSE_DATABASE!,
+  useSSL: true,
+});
+
+// Define your table (compiler plugin injects schema at build time)
+const myTable = new OlapTable<MyType>("my_table");
+
+export async function handler(event: any) {
+  const data = parseEvent(event);
+  await myTable.insert(data);  // Works without moose.config.toml
+  return { statusCode: 200 };
+}
+```
+
+### `ClickHouseConfig` fields
+
+| Field | Type | Example |
+| --- | --- | --- |
+| `host` | `string` | `"clickhouse.example.com"` |
+| `port` | `string` | `"8443"` |
+| `username` | `string` | `"default"` |
+| `password` | `string` | `"secret"` |
+| `database` | `string` | `"my_database"` |
+| `useSSL` | `boolean` | `true` |
 
 ## What's Included
 
@@ -98,6 +138,8 @@ import { OlapTable, Stream, sql } from "@bayoudhi/moose-lib-serverless";
 | ClickHouse column types | `Columns.String`, `Columns.Int32`, `Columns.DateTime`, etc. |
 | `ConsumptionUtil`, `ApiUtil` | Utility types for consumption APIs |
 | `registerDataSource` | Register external data source connectors |
+| `configureClickHouse` | Provide ClickHouse connection config for serverless (no `moose.config.toml`) |
+| `ClickHouseConfig` | TypeScript interface for `configureClickHouse()` options |
 | `getSecrets` | Retrieve secrets from the Moose secrets store |
 | Utility functions | `compilerLog`, `cliLog`, `mapTstoJs`, `getFileName`, etc. |
 

package/dist/index.d.mts

@@ -2698,4 +2698,66 @@ interface ExtractionResult<T = any> {
     metadata: Record<string, any>;
 }
 
-export { ACKs, type Aggregated, Api, type ApiConfig, type ApiUtil, type CSVParsingConfig, CSV_DELIMITERS, type CliLogData, type ClickHouseByteSize, type ClickHouseCodec, type ClickHouseDecimal, type ClickHouseDefault, ClickHouseEngines, type ClickHouseFixedStringSize, type ClickHouseFloat, type ClickHouseInt, type ClickHouseJson, type ClickHouseMaterialized, type ClickHouseNamedTuple, type ClickHousePrecision, type ClickHouseTTL, ConsumptionApi, type ConsumptionUtil, DEFAULT_CSV_CONFIG, DEFAULT_JSON_CONFIG, DataSource, type DataSourceConfig, type DateTime, type DateTime64, type DateTime64String, type DateTimeString, type DeadLetter, type DeadLetterModel, DeadLetterQueue, type Decimal, ETLPipeline, type ETLPipelineConfig, type EgressConfig, type ExtractionResult, type FixedString, type Float32, type Float64, type FrameworkApp, type IdentifierBrandedString, IngestApi, type IngestConfig, IngestPipeline, type Int16, type Int32, type Int64, type Int8, type JSONParsingConfig, type JWT, type KafkaClientConfig, type Key, LifeCycle, type Logger, type LowCardinality, MAX_RETRIES, MAX_RETRIES_PRODUCER, MAX_RETRY_TIME_MS, MOOSE_RUNTIME_ENV_PREFIX, MaterializedView, type NonIdentifierBrandedString, type OlapConfig, OlapTable, RETRY_FACTOR_PRODUCER, RETRY_INITIAL_TIME_MS, type RawValue, type S3QueueTableSettings, type SimpleAggregated, Sql, SqlResource, type SqlTemplateTag, Stream, type StreamConfig, type StripDateIntersection, Task, type UInt16, type UInt32, type UInt64, type UInt8, type Value, View, WebApp, type WebAppConfig, type WebAppHandler, type WithDefault, Workflow, antiCachePath, cliLog, compilerLog, createClickhouseParameter, getApi, getApis, getFileName, getIngestApi, getIngestApis, getMaterializedView, getMaterializedViews, getSqlResource, getSqlResources, getStream, getStreams, getTable, getTables, getValueFromParameter, getView, getViews, getWebApp, getWebApps, getWorkflow, getWorkflows, isValidCSVDelimiter, logError, mapToClickHouseType, mapTstoJs, mooseEnvSecrets, mooseRuntimeEnv, parseCSV, parseJSON, parseJSONWithDates, quoteIdentifier, sql, toQuery, toQueryPreview, toStaticQuery };
+/**
+ * @module @bayoudhi/moose-lib-serverless
+ *
+ * Serverless-compatible subset of @514labs/moose-lib.
+ *
+ * Re-exports everything from the `@514labs/moose-lib/serverless` entry point,
+ * which excludes native C++ dependencies (Kafka, Temporal, Redis) that are
+ * incompatible with AWS Lambda and edge runtimes.
+ *
+ * At build time, `@514labs/moose-lib` code is inlined into this package's
+ * bundle so there is no runtime dependency on `@514labs/moose-lib`.
+ */
+
+/**
+ * ClickHouse connection configuration for serverless environments.
+ *
+ * In a standard Moose project, connection details are read from
+ * `moose.config.toml`. In serverless environments (AWS Lambda, Edge, etc.)
+ * this file doesn't exist, so you must provide the config programmatically
+ * via {@link configureClickHouse} before calling `.insert()` on any table.
+ */
+interface ClickHouseConfig {
+    /** ClickHouse host (e.g. "clickhouse.example.com") */
+    host: string;
+    /** ClickHouse HTTP port as a string (e.g. "8443") */
+    port: string;
+    /** ClickHouse username (e.g. "default") */
+    username: string;
+    /** ClickHouse password */
+    password: string;
+    /** ClickHouse database name */
+    database: string;
+    /** Whether to use HTTPS/SSL for the connection */
+    useSSL: boolean;
+}
+/**
+ * Configure the ClickHouse connection for serverless environments.
+ *
+ * Call this once during cold start (before any `.insert()` calls) to provide
+ * ClickHouse connection details. This bypasses the `moose.config.toml` file
+ * lookup that would otherwise fail in environments without a Moose project
+ * structure.
+ *
+ * @example
+ * ```typescript
+ * import { configureClickHouse, OlapTable } from "@bayoudhi/moose-lib-serverless";
+ *
+ * configureClickHouse({
+ *   host: process.env.CLICKHOUSE_HOST!,
+ *   port: process.env.CLICKHOUSE_PORT!,
+ *   username: process.env.CLICKHOUSE_USER!,
+ *   password: process.env.CLICKHOUSE_PASSWORD!,
+ *   database: process.env.CLICKHOUSE_DATABASE!,
+ *   useSSL: true,
+ * });
+ *
+ * // Now .insert() works without moose.config.toml
+ * await myTable.insert(data);
+ * ```
+ */
+declare function configureClickHouse(config: ClickHouseConfig): void;
+
+export { ACKs, type Aggregated, Api, type ApiConfig, type ApiUtil, type CSVParsingConfig, CSV_DELIMITERS, type CliLogData, type ClickHouseByteSize, type ClickHouseCodec, type ClickHouseConfig, type ClickHouseDecimal, type ClickHouseDefault, ClickHouseEngines, type ClickHouseFixedStringSize, type ClickHouseFloat, type ClickHouseInt, type ClickHouseJson, type ClickHouseMaterialized, type ClickHouseNamedTuple, type ClickHousePrecision, type ClickHouseTTL, ConsumptionApi, type ConsumptionUtil, DEFAULT_CSV_CONFIG, DEFAULT_JSON_CONFIG, DataSource, type DataSourceConfig, type DateTime, type DateTime64, type DateTime64String, type DateTimeString, type DeadLetter, type DeadLetterModel, DeadLetterQueue, type Decimal, ETLPipeline, type ETLPipelineConfig, type EgressConfig, type ExtractionResult, type FixedString, type Float32, type Float64, type FrameworkApp, type IdentifierBrandedString, IngestApi, type IngestConfig, IngestPipeline, type Int16, type Int32, type Int64, type Int8, type JSONParsingConfig, type JWT, type KafkaClientConfig, type Key, LifeCycle, type Logger, type LowCardinality, MAX_RETRIES, MAX_RETRIES_PRODUCER, MAX_RETRY_TIME_MS, MOOSE_RUNTIME_ENV_PREFIX, MaterializedView, type NonIdentifierBrandedString, type OlapConfig, OlapTable, RETRY_FACTOR_PRODUCER, RETRY_INITIAL_TIME_MS, type RawValue, type S3QueueTableSettings, type SimpleAggregated, Sql, SqlResource, type SqlTemplateTag, Stream, type StreamConfig, type StripDateIntersection, Task, type UInt16, type UInt32, type UInt64, type UInt8, type Value, View, WebApp, type WebAppConfig, type WebAppHandler, type WithDefault, Workflow, antiCachePath, cliLog, compilerLog, configureClickHouse, createClickhouseParameter, getApi, getApis, getFileName, getIngestApi, getIngestApis, getMaterializedView, getMaterializedViews, getSqlResource, getSqlResources, getStream, getStreams, getTable, getTables, getValueFromParameter, getView, getViews, getWebApp, getWebApps, getWorkflow, getWorkflows, isValidCSVDelimiter, logError, mapToClickHouseType, mapTstoJs, mooseEnvSecrets, mooseRuntimeEnv, parseCSV, parseJSON, parseJSONWithDates, quoteIdentifier, sql, toQuery, toQueryPreview, toStaticQuery };

package/dist/index.d.ts

@@ -2698,4 +2698,66 @@ interface ExtractionResult<T = any> {
     metadata: Record<string, any>;
 }
 
-export { ACKs, type Aggregated, Api, type ApiConfig, type ApiUtil, type CSVParsingConfig, CSV_DELIMITERS, type CliLogData, type ClickHouseByteSize, type ClickHouseCodec, type ClickHouseDecimal, type ClickHouseDefault, ClickHouseEngines, type ClickHouseFixedStringSize, type ClickHouseFloat, type ClickHouseInt, type ClickHouseJson, type ClickHouseMaterialized, type ClickHouseNamedTuple, type ClickHousePrecision, type ClickHouseTTL, ConsumptionApi, type ConsumptionUtil, DEFAULT_CSV_CONFIG, DEFAULT_JSON_CONFIG, DataSource, type DataSourceConfig, type DateTime, type DateTime64, type DateTime64String, type DateTimeString, type DeadLetter, type DeadLetterModel, DeadLetterQueue, type Decimal, ETLPipeline, type ETLPipelineConfig, type EgressConfig, type ExtractionResult, type FixedString, type Float32, type Float64, type FrameworkApp, type IdentifierBrandedString, IngestApi, type IngestConfig, IngestPipeline, type Int16, type Int32, type Int64, type Int8, type JSONParsingConfig, type JWT, type KafkaClientConfig, type Key, LifeCycle, type Logger, type LowCardinality, MAX_RETRIES, MAX_RETRIES_PRODUCER, MAX_RETRY_TIME_MS, MOOSE_RUNTIME_ENV_PREFIX, MaterializedView, type NonIdentifierBrandedString, type OlapConfig, OlapTable, RETRY_FACTOR_PRODUCER, RETRY_INITIAL_TIME_MS, type RawValue, type S3QueueTableSettings, type SimpleAggregated, Sql, SqlResource, type SqlTemplateTag, Stream, type StreamConfig, type StripDateIntersection, Task, type UInt16, type UInt32, type UInt64, type UInt8, type Value, View, WebApp, type WebAppConfig, type WebAppHandler, type WithDefault, Workflow, antiCachePath, cliLog, compilerLog, createClickhouseParameter, getApi, getApis, getFileName, getIngestApi, getIngestApis, getMaterializedView, getMaterializedViews, getSqlResource, getSqlResources, getStream, getStreams, getTable, getTables, getValueFromParameter, getView, getViews, getWebApp, getWebApps, getWorkflow, getWorkflows, isValidCSVDelimiter, logError, mapToClickHouseType, mapTstoJs, mooseEnvSecrets, mooseRuntimeEnv, parseCSV, parseJSON, parseJSONWithDates, quoteIdentifier, sql, toQuery, toQueryPreview, toStaticQuery };
+/**
+ * @module @bayoudhi/moose-lib-serverless
+ *
+ * Serverless-compatible subset of @514labs/moose-lib.
+ *
+ * Re-exports everything from the `@514labs/moose-lib/serverless` entry point,
+ * which excludes native C++ dependencies (Kafka, Temporal, Redis) that are
+ * incompatible with AWS Lambda and edge runtimes.
+ *
+ * At build time, `@514labs/moose-lib` code is inlined into this package's
+ * bundle so there is no runtime dependency on `@514labs/moose-lib`.
+ */
+
+/**
+ * ClickHouse connection configuration for serverless environments.
+ *
+ * In a standard Moose project, connection details are read from
+ * `moose.config.toml`. In serverless environments (AWS Lambda, Edge, etc.)
+ * this file doesn't exist, so you must provide the config programmatically
+ * via {@link configureClickHouse} before calling `.insert()` on any table.
+ */
+interface ClickHouseConfig {
+    /** ClickHouse host (e.g. "clickhouse.example.com") */
+    host: string;
+    /** ClickHouse HTTP port as a string (e.g. "8443") */
+    port: string;
+    /** ClickHouse username (e.g. "default") */
+    username: string;
+    /** ClickHouse password */
+    password: string;
+    /** ClickHouse database name */
+    database: string;
+    /** Whether to use HTTPS/SSL for the connection */
+    useSSL: boolean;
+}
+/**
+ * Configure the ClickHouse connection for serverless environments.
+ *
+ * Call this once during cold start (before any `.insert()` calls) to provide
+ * ClickHouse connection details. This bypasses the `moose.config.toml` file
+ * lookup that would otherwise fail in environments without a Moose project
+ * structure.
+ *
+ * @example
+ * ```typescript
+ * import { configureClickHouse, OlapTable } from "@bayoudhi/moose-lib-serverless";
+ *
+ * configureClickHouse({
+ *   host: process.env.CLICKHOUSE_HOST!,
+ *   port: process.env.CLICKHOUSE_PORT!,
+ *   username: process.env.CLICKHOUSE_USER!,
+ *   password: process.env.CLICKHOUSE_PASSWORD!,
+ *   database: process.env.CLICKHOUSE_DATABASE!,
+ *   useSSL: true,
+ * });
+ *
+ * // Now .insert() works without moose.config.toml
+ * await myTable.insert(data);
+ * ```
+ */
+declare function configureClickHouse(config: ClickHouseConfig): void;
+
+export { ACKs, type Aggregated, Api, type ApiConfig, type ApiUtil, type CSVParsingConfig, CSV_DELIMITERS, type CliLogData, type ClickHouseByteSize, type ClickHouseCodec, type ClickHouseConfig, type ClickHouseDecimal, type ClickHouseDefault, ClickHouseEngines, type ClickHouseFixedStringSize, type ClickHouseFloat, type ClickHouseInt, type ClickHouseJson, type ClickHouseMaterialized, type ClickHouseNamedTuple, type ClickHousePrecision, type ClickHouseTTL, ConsumptionApi, type ConsumptionUtil, DEFAULT_CSV_CONFIG, DEFAULT_JSON_CONFIG, DataSource, type DataSourceConfig, type DateTime, type DateTime64, type DateTime64String, type DateTimeString, type DeadLetter, type DeadLetterModel, DeadLetterQueue, type Decimal, ETLPipeline, type ETLPipelineConfig, type EgressConfig, type ExtractionResult, type FixedString, type Float32, type Float64, type FrameworkApp, type IdentifierBrandedString, IngestApi, type IngestConfig, IngestPipeline, type Int16, type Int32, type Int64, type Int8, type JSONParsingConfig, type JWT, type KafkaClientConfig, type Key, LifeCycle, type Logger, type LowCardinality, MAX_RETRIES, MAX_RETRIES_PRODUCER, MAX_RETRY_TIME_MS, MOOSE_RUNTIME_ENV_PREFIX, MaterializedView, type NonIdentifierBrandedString, type OlapConfig, OlapTable, RETRY_FACTOR_PRODUCER, RETRY_INITIAL_TIME_MS, type RawValue, type S3QueueTableSettings, type SimpleAggregated, Sql, SqlResource, type SqlTemplateTag, Stream, type StreamConfig, type StripDateIntersection, Task, type UInt16, type UInt32, type UInt64, type UInt8, type Value, View, WebApp, type WebAppConfig, type WebAppHandler, type WithDefault, Workflow, antiCachePath, cliLog, compilerLog, configureClickHouse, createClickhouseParameter, getApi, getApis, getFileName, getIngestApi, getIngestApis, getMaterializedView, getMaterializedViews, getSqlResource, getSqlResources, getStream, getStreams, getTable, getTables, getValueFromParameter, getView, getViews, getWebApp, getWebApps, getWorkflow, getWorkflows, isValidCSVDelimiter, logError, mapToClickHouseType, mapTstoJs, mooseEnvSecrets, mooseRuntimeEnv, parseCSV, parseJSON, parseJSONWithDates, quoteIdentifier, sql, toQuery, toQueryPreview, toStaticQuery };

package/dist/index.js

@@ -220,6 +220,7 @@ __export(index_exports, {
   antiCachePath: () => antiCachePath,
   cliLog: () => cliLog,
   compilerLog: () => compilerLog,
+  configureClickHouse: () => configureClickHouse,
   createClickhouseParameter: () => createClickhouseParameter,
   getApi: () => getApi,
   getApis: () => getApis,
@@ -3157,6 +3158,39 @@ function getView(name) {
   return getMooseInternal().views.get(name);
 }
 init_commons();
+
+// src/index.ts
+var _pendingClickHouseConfig = null;
+function configureClickHouse(config) {
+  const registry = globalThis._mooseConfigRegistry;
+  if (registry && typeof registry.setClickHouseConfig === "function") {
+    registry.setClickHouseConfig(config);
+    _pendingClickHouseConfig = null;
+    return;
+  }
+  _pendingClickHouseConfig = config;
+  let _realRegistry = null;
+  Object.defineProperty(globalThis, "_mooseConfigRegistry", {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return _realRegistry;
+    },
+    set(newRegistry) {
+      _realRegistry = newRegistry;
+      if (_pendingClickHouseConfig && typeof newRegistry.setClickHouseConfig === "function") {
+        newRegistry.setClickHouseConfig(_pendingClickHouseConfig);
+        _pendingClickHouseConfig = null;
+      }
+      Object.defineProperty(globalThis, "_mooseConfigRegistry", {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: newRegistry
+      });
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACKs,
@@ -3190,6 +3224,7 @@ init_commons();
   antiCachePath,
   cliLog,
   compilerLog,
+  configureClickHouse,
   createClickhouseParameter,
   getApi,
   getApis,