@514labs/moose-lib 0.6.527 → 0.6.528

package/dist/dmv2/index.mjs

@@ -633,6 +633,7 @@ var quoteIdentifier = (name) => {
 };
 var isTable = (value) => typeof value === "object" && value !== null && "kind" in value && value.kind === "OlapTable";
 var isView = (value) => typeof value === "object" && value !== null && "kind" in value && value.kind === "View";
+var isDictionary = (value) => typeof value === "object" && value !== null && "kind" in value && value.kind === "OlapDictionary";
 var isColumn = (value) => typeof value === "object" && value !== null && !("kind" in value) && "name" in value && "annotations" in value;
 function sqlImpl(strings, ...values) {
   return new Sql(strings, values);
@@ -659,7 +660,7 @@ var Sql = class _Sql {
       );
     }
     const valuesLength = rawValues.reduce(
-      (len, value) => len + (instanceofSql(value) ? value.values.length : isColumn(value) || isTable(value) || isView(value) ? 0 : 1),
+      (len, value) => len + (instanceofSql(value) ? value.values.length : isColumn(value) || isTable(value) || isView(value) || isDictionary(value) ? 0 : 1),
       0
     );
     this.values = new Array(valuesLength);
@@ -706,6 +707,14 @@ var Sql = class _Sql {
           this.strings[pos] += `\`${child.name}\``;
         }
         this.strings[pos] += rawString;
+      } else if (isDictionary(child)) {
+        if (/\b(?:FROM|JOIN)\s*$/i.test(this.strings[pos])) {
+          console.warn(
+            `OlapDictionary '${child.getQualifiedName()}' interpolated after FROM/JOIN in sql tag. Dictionaries render as string literals (e.g. 'db.dict_name') for use with dictGet(), not as table identifiers. ClickHouse dictionaries cannot be queried directly with FROM/JOIN.`
+          );
+        }
+        this.strings[pos] += `'${child.getQualifiedName().replace(/'/g, "''")}'`;
+        this.strings[pos] += rawString;
       } else {
         this.values[pos++] = child;
         this.strings[pos] = rawString;
@@ -949,6 +958,12 @@ function getSelectRowPolicies() {
 function getSelectRowPolicy(name) {
   return getMooseInternal().selectRowPolicies.get(name);
 }
+function getOlapDictionaries() {
+  return getMooseInternal().olapDictionaries;
+}
+function getOlapDictionary(name) {
+  return getMooseInternal().olapDictionaries.get(name);
+}
 
 // src/consumption-apis/standalone.ts
 import { AsyncLocalStorage } from "async_hooks";
@@ -1146,7 +1161,8 @@ function createRegistryFrom(existing) {
     webApps: toTrackingMap(existing?.webApps),
     materializedViews: toTrackingMap(existing?.materializedViews),
     views: toTrackingMap(existing?.views),
-    selectRowPolicies: toTrackingMap(existing?.selectRowPolicies)
+    selectRowPolicies: toTrackingMap(existing?.selectRowPolicies),
+    olapDictionaries: toTrackingMap(existing?.olapDictionaries)
   };
 }
 var moose_internal = {
@@ -1186,6 +1202,10 @@ var moose_internal = {
   selectRowPolicies: new MutationTrackingMap(
     void 0,
     markRegistryMutated
+  ),
+  olapDictionaries: new MutationTrackingMap(
+    void 0,
+    markRegistryMutated
   )
 };
 var defaultRetentionPeriod = 60 * 60 * 24 * 7;
@@ -3067,6 +3087,369 @@ var LifeCycle = /* @__PURE__ */ ((LifeCycle2) => {
   return LifeCycle2;
 })(LifeCycle || {});
 
+// src/dmv2/sdk/olapDictionary.ts
+var COMPLEX_KEY_LAYOUTS = /* @__PURE__ */ new Set([
+  "COMPLEX_KEY_HASHED",
+  "COMPLEX_KEY_SPARSE_HASHED",
+  "COMPLEX_KEY_HASHED_ARRAY",
+  "COMPLEX_KEY_CACHE",
+  "COMPLEX_KEY_SSD_CACHE",
+  "COMPLEX_KEY_DIRECT"
+]);
+function dataTypeToString(dataType) {
+  if (typeof dataType === "string") {
+    return dataType;
+  }
+  if (typeof dataType === "object" && dataType !== null) {
+    if ("nullable" in dataType) {
+      const inner = dataTypeToString(
+        dataType.nullable
+      );
+      return `Nullable(${inner})`;
+    }
+    if ("elementType" in dataType) {
+      const arr = dataType;
+      const inner = dataTypeToString(arr.elementType);
+      return arr.elementNullable ? `Array(Nullable(${inner}))` : `Array(${inner})`;
+    }
+    if ("name" in dataType && "values" in dataType) {
+      const d = dataType;
+      const entries = d.values.map(
+        (v) => v.value.String !== void 0 ? `'${v.name}' = '${v.value.String}'` : `'${v.name}' = ${v.value.Int ?? 0}`
+      ).join(", ");
+      return `${d.name}(${entries})`;
+    }
+  }
+  throw new Error(
+    `OlapDictionary: unsupported column data type for dictionary attribute: ${JSON.stringify(dataType)}. Dictionaries only support scalar value types (strings, integers, floats, booleans, dates, Nullable wrappers, Array wrappers, and Enum types).`
+  );
+}
+function buildDictionaryColumns(columns, overrides) {
+  return columns.map((col) => {
+    const override = overrides?.[col.name] ?? {};
+    const result = {
+      name: col.name,
+      typeString: dataTypeToString(col.data_type)
+    };
+    if (override.defaultValue !== void 0)
+      result.defaultValue = override.defaultValue;
+    if (override.expression !== void 0)
+      result.expression = override.expression;
+    if (override.isInjective !== void 0)
+      result.isInjective = override.isInjective;
+    if (override.isHierarchical !== void 0)
+      result.isHierarchical = override.isHierarchical;
+    if (override.isObjectId !== void 0)
+      result.isObjectId = override.isObjectId;
+    if (override.comment !== void 0) result.comment = override.comment;
+    return result;
+  });
+}
+function serializeLifetime(lifetime) {
+  if (typeof lifetime === "number") {
+    if (!Number.isFinite(lifetime) || lifetime < 0 || !Number.isInteger(lifetime)) {
+      throw new Error(
+        `OlapDictionary: lifetime must be a finite non-negative integer (got ${lifetime}).`
+      );
+    }
+    if (lifetime === 0) {
+      return { type: "STATIC" };
+    }
+    return { type: "SINGLE", seconds: lifetime };
+  }
+  if (!Number.isFinite(lifetime.min) || !Number.isFinite(lifetime.max) || !Number.isInteger(lifetime.min) || !Number.isInteger(lifetime.max) || lifetime.min < 0 || lifetime.max < lifetime.min) {
+    throw new Error(
+      `OlapDictionary: lifetime range must use finite non-negative integers with min <= max (got min=${lifetime.min}, max=${lifetime.max}).`
+    );
+  }
+  if (lifetime.min === 0 && lifetime.max === 0) {
+    return { type: "STATIC" };
+  }
+  if (lifetime.min === lifetime.max) {
+    return { type: "SINGLE", seconds: lifetime.min };
+  }
+  return { type: "RANGE", min: lifetime.min, max: lifetime.max };
+}
+function serializeLayout(layout) {
+  const { type, ...rest } = layout;
+  const snakeCaseFields = {};
+  for (const [key, value] of Object.entries(rest)) {
+    if (value === void 0) continue;
+    const snake = key.replace(/([A-Z])/g, "_$1").toLowerCase();
+    snakeCaseFields[snake] = value;
+  }
+  return { type, ...snakeCaseFields };
+}
+function externalTypeToRust(type) {
+  const mapping = {
+    http: "HTTP",
+    clickhouse: "CLICK_HOUSE",
+    mysql: "MYSQL",
+    postgresql: "POSTGRESQL",
+    redis: "REDIS",
+    mongodb: "MONGODB",
+    executable: "EXECUTABLE",
+    s3: "S3"
+  };
+  return mapping[type];
+}
+function serializeExternalSource(ext) {
+  const { type, ...rest } = ext;
+  const inner = {
+    source_type: externalTypeToRust(type)
+  };
+  for (const [key, value] of Object.entries(rest)) {
+    inner[key] = value;
+  }
+  return {
+    type: "EXTERNAL",
+    externalSource: inner
+  };
+}
+function serializeSource(config) {
+  if (config.sourceTable !== void 0) {
+    const table = config.sourceTable;
+    if (table instanceof OlapTable) {
+      return {
+        type: "TABLE",
+        table: table.generateTableName(),
+        database: table.config.database,
+        ...config.invalidateQuery !== void 0 ? { invalidateQuery: config.invalidateQuery } : {}
+      };
+    } else {
+      return {
+        type: "TABLE",
+        table: table.name,
+        database: table.database,
+        ...config.invalidateQuery !== void 0 ? { invalidateQuery: config.invalidateQuery } : {}
+      };
+    }
+  }
+  if (config.sourceQuery !== void 0) {
+    return {
+      type: "QUERY",
+      query: toStaticQuery(config.sourceQuery),
+      ...config.invalidateQuery !== void 0 ? { invalidateQuery: config.invalidateQuery } : {}
+    };
+  }
+  if (config.externalSource !== void 0) {
+    return serializeExternalSource(config.externalSource);
+  }
+  throw new Error(
+    "OlapDictionary: no source configured (unreachable after validation)"
+  );
+}
+var OlapDictionary = class {
+  /** @internal */
+  kind = "OlapDictionary";
+  /** Dictionary name */
+  name;
+  /** User configuration */
+  config;
+  /** Compiler-injected columns (name + type from T) */
+  _columns;
+  /** Serialized column list (DictionaryColumn JSON objects) */
+  serializedColumns;
+  constructor(name, config, _schema, columns) {
+    if (_schema === void 0 || columns === void 0) {
+      throw new Error(
+        "Supply the type param T so that the schema is inserted by the compiler plugin."
+      );
+    }
+    this.name = name;
+    this.config = config;
+    this._columns = columns;
+    const sourcesSet = [
+      config.sourceTable !== void 0,
+      config.sourceQuery !== void 0,
+      config.externalSource !== void 0
+    ].filter(Boolean).length;
+    if (sourcesSet === 0) {
+      throw new Error(
+        `OlapDictionary '${name}': exactly one of sourceTable, sourceQuery, or externalSource must be set (none provided).`
+      );
+    }
+    if (sourcesSet > 1) {
+      throw new Error(
+        `OlapDictionary '${name}': exactly one of sourceTable, sourceQuery, or externalSource must be set (${sourcesSet} provided).`
+      );
+    }
+    if (config.sourceQuery !== void 0 && !config.sourceTables?.length) {
+      throw new Error(
+        `OlapDictionary '${name}': sourceQuery requires sourceTables to be set for dependency tracking.`
+      );
+    }
+    if (config.sourceQuery !== void 0) {
+      if (!toStaticQuery(config.sourceQuery).trim()) {
+        throw new Error(
+          `OlapDictionary '${name}': sourceQuery must not be blank.`
+        );
+      }
+    }
+    if (!config.primaryKey.length) {
+      throw new Error(
+        `OlapDictionary '${name}': primaryKey must contain at least one column name.`
+      );
+    }
+    if (!COMPLEX_KEY_LAYOUTS.has(config.layout.type)) {
+      if (config.primaryKey.length !== 1) {
+        throw new Error(
+          `OlapDictionary '${name}': layout '${config.layout.type}' requires exactly 1 primary key column (got ${config.primaryKey.length}). Use a COMPLEX_KEY_* layout for string or multi-column keys.`
+        );
+      }
+    }
+    this.serializedColumns = buildDictionaryColumns(
+      columns,
+      config.columns
+    );
+    if (!config.metadata?.source) {
+      const stack = new Error().stack;
+      const sourceInfo = getSourceFileFromStack(stack);
+      if (sourceInfo) {
+        this.config.metadata = {
+          ...config.metadata,
+          source: { file: sourceInfo }
+        };
+      }
+    }
+    const olapDictionaries = getMooseInternal().olapDictionaries;
+    if (!isClientOnlyMode() && olapDictionaries.has(name)) {
+      throw new Error(`OlapDictionary with name '${name}' already exists`);
+    }
+    olapDictionaries.set(name, this);
+  }
+  /**
+   * Returns the qualified dictionary name for use in dictGet calls.
+   * Format: `database.name` if database is set, otherwise just `name`.
+   */
+  getQualifiedName() {
+    if (this.config.database) {
+      return `${this.config.database}.${this.name}`;
+    }
+    return this.name;
+  }
+  /**
+   * Formats key arguments for use in dictGet/dictHas SQL functions.
+   * Strings are treated as SQL identifiers, numbers as literals.
+   */
+  formatKeyArgs(keys) {
+    if (keys.length !== this.config.primaryKey.length) {
+      throw new Error(
+        `OlapDictionary '${this.name}': expected ${this.config.primaryKey.length} key argument(s) but got ${keys.length}.`
+      );
+    }
+    const parts = keys.map((k) => {
+      if (typeof k === "object" && "strings" in k) {
+        return toStaticQuery(k);
+      }
+      if (typeof k === "string") {
+        return `\`${k.replace(/`/g, "``")}\``;
+      }
+      return String(k);
+    });
+    return parts.length === 1 ? parts[0] : `(${parts.join(", ")})`;
+  }
+  /**
+   * Generates a `dictGet('dict', 'attr', key)` SQL fragment.
+   *
+   * @param attr - The attribute (column) name to retrieve
+   * @param keys - Key expression(s). Strings are treated as column identifiers.
+   *
+   * @example
+   * ```typescript
+   * sql`SELECT ${ProductDict.get("ProductName", "product_id")} AS name FROM ...`
+   * // → SELECT dictGet('db.dict_products', 'ProductName', `product_id`) AS name FROM ...
+   * ```
+   */
+  get(attr, ...keys) {
+    if (!keys.length) {
+      throw new Error(
+        `OlapDictionary.get('${attr}'): at least one key argument is required.`
+      );
+    }
+    const qualifiedName = this.getQualifiedName().replace(/'/g, "''");
+    const escapedAttr = attr.replace(/'/g, "''");
+    const keyExpr = this.formatKeyArgs(keys);
+    return sql.raw(`dictGet('${qualifiedName}', '${escapedAttr}', ${keyExpr})`);
+  }
+  /**
+   * Generates a `dictGetOrDefault('dict', 'attr', key, default)` SQL fragment.
+   *
+   * @param attr - The attribute (column) name to retrieve
+   * @param defaultVal - The default value if the key is not found
+   * @param keys - Key expression(s)
+   */
+  getOrDefault(attr, defaultVal, ...keys) {
+    if (!keys.length) {
+      throw new Error(
+        `OlapDictionary.getOrDefault('${attr}'): at least one key argument is required.`
+      );
+    }
+    const qualifiedName = this.getQualifiedName().replace(/'/g, "''");
+    const escapedAttr = attr.replace(/'/g, "''");
+    const keyExpr = this.formatKeyArgs(keys);
+    let defaultExpr;
+    if (typeof defaultVal === "object" && "strings" in defaultVal) {
+      defaultExpr = toStaticQuery(defaultVal);
+    } else if (typeof defaultVal === "string") {
+      defaultExpr = `'${defaultVal.replace(/'/g, "''")}'`;
+    } else {
+      defaultExpr = String(defaultVal);
+    }
+    return sql.raw(
+      `dictGetOrDefault('${qualifiedName}', '${escapedAttr}', ${keyExpr}, ${defaultExpr})`
+    );
+  }
+  /**
+   * Generates a `dictHas('dict', key)` SQL fragment.
+   *
+   * @param keys - Key expression(s)
+   *
+   * @example
+   * ```typescript
+   * sql`SELECT * FROM source WHERE ${ProductDict.has("product_id")}`
+   * // → SELECT * FROM source WHERE dictHas('db.dict_products', `product_id`)
+   * ```
+   */
+  has(...keys) {
+    if (!keys.length) {
+      throw new Error(
+        `OlapDictionary.has(): at least one key argument is required.`
+      );
+    }
+    const qualifiedName = this.getQualifiedName().replace(/'/g, "''");
+    const keyExpr = this.formatKeyArgs(keys);
+    return sql.raw(`dictHas('${qualifiedName}', ${keyExpr})`);
+  }
+  /**
+   * Serializes this dictionary to the JSON format expected by the Rust CLI.
+   * @internal
+   */
+  toJson() {
+    const source = serializeSource(this.config);
+    const result = {
+      name: this.name,
+      source,
+      primaryKey: this.config.primaryKey,
+      columns: this.serializedColumns,
+      layout: serializeLayout(this.config.layout),
+      lifetime: serializeLifetime(this.config.lifetime),
+      settings: this.config.settings ?? {},
+      lifeCycle: this.config.lifeCycle ?? "FULLY_MANAGED" /* FULLY_MANAGED */
+    };
+    if (this.config.database !== void 0)
+      result.database = this.config.database;
+    if (this.config.clusterName !== void 0)
+      result.clusterName = this.config.clusterName;
+    if (this.config.invalidateQuery !== void 0)
+      result.invalidateQuery = this.config.invalidateQuery;
+    if (this.config.comment !== void 0) result.comment = this.config.comment;
+    if (this.config.metadata !== void 0)
+      result.metadata = this.config.metadata;
+    return result;
+  }
+};
+
 // src/dmv2/sdk/webApp.ts
 var RESERVED_MOUNT_PATHS = [
   "/admin",
@@ -3195,6 +3578,7 @@ Examples:
 };
 export {
   Api,
+  COMPLEX_KEY_LAYOUTS,
   ClickHouseEngines,
   ConsumptionApi,
   DeadLetterQueue,
@@ -3203,6 +3587,7 @@ export {
   IngestPipeline,
   LifeCycle,
   MaterializedView,
+  OlapDictionary,
   OlapTable,
   SelectRowPolicy,
   SqlResource,
@@ -3217,6 +3602,8 @@ export {
   getIngestApis,
   getMaterializedView,
   getMaterializedViews,
+  getOlapDictionaries,
+  getOlapDictionary,
   getSelectRowPolicies,
   getSelectRowPolicy,
   getSqlResource,