@malloydata/malloy 0.0.372 → 0.0.374

package/dist/api/foundation/config_compile.d.ts

@@ -0,0 +1,34 @@
+import type { LogMessage } from '../../lang/parse-log';
+/**
+ * A compiled config node. The compiler produces a tree of these; the resolver
+ * walks the tree against a ConfigOverlays dict and produces a plain POJO.
+ */
+export type ConfigNode = ConfigDict | ConfigLiteral | ConfigReference;
+export interface ConfigDict {
+    kind: 'dict';
+    entries: Record<string, ConfigNode>;
+}
+/**
+ * A leaf node holding a literal — primitives for typed slots, arbitrary
+ * JSON for `json`-typed slots (no reference expansion, no type checking).
+ */
+export interface ConfigLiteral {
+    kind: 'value';
+    value: unknown;
+}
+export interface ConfigReference {
+    kind: 'reference';
+    /** Overlay name: "env", "config", "session", etc. */
+    source: string;
+    /** Path into the overlay. */
+    path: string[];
+}
+export type SectionCompiler = (value: unknown, log: LogMessage[]) => ConfigNode | undefined;
+/**
+ * Compile a POJO into a typed dictionary tree, collecting validation warnings.
+ * Does not throw — caller inspects `log` for issues.
+ */
+export declare function compileConfig(pojo: unknown): {
+    compiled: ConfigDict;
+    log: LogMessage[];
+};

package/dist/api/foundation/config_compile.js

@@ -0,0 +1,247 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileConfig = compileConfig;
+const registry_1 = require("../../connection/registry");
+const TOP_LEVEL_SECTIONS = {
+    connections: compileConnections,
+    manifestPath: compileManifestPath,
+    virtualMap: compileVirtualMap,
+    includeDefaultConnections: compileIncludeDefaultConnections,
+};
+const KNOWN_TOP_LEVEL_KEYS = new Set(Object.keys(TOP_LEVEL_SECTIONS));
+// =============================================================================
+// Entry point
+// =============================================================================
+/**
+ * Compile a POJO into a typed dictionary tree, collecting validation warnings.
+ * Does not throw — caller inspects `log` for issues.
+ */
+function compileConfig(pojo) {
+    const log = [];
+    const compiled = { kind: 'dict', entries: {} };
+    if (!isRecord(pojo)) {
+        log.push({
+            message: 'config is not a JSON object',
+            severity: 'error',
+            code: 'config-validation',
+        });
+        return { compiled, log };
+    }
+    for (const [key, value] of Object.entries(pojo)) {
+        const compiler = TOP_LEVEL_SECTIONS[key];
+        if (!compiler) {
+            const suggestion = closestMatch(key, [...KNOWN_TOP_LEVEL_KEYS]);
+            const hint = suggestion ? `. Did you mean "${suggestion}"?` : '';
+            log.push(makeWarning(key, `unknown config key "${key}"${hint}`));
+            continue;
+        }
+        const node = compiler(value, log);
+        if (node !== undefined) {
+            compiled.entries[key] = node;
+        }
+    }
+    return { compiled, log };
+}
+// =============================================================================
+// connections
+// =============================================================================
+function compileConnections(value, log) {
+    if (!isRecord(value)) {
+        log.push(makeWarning('connections', '"connections" should be an object'));
+        return undefined;
+    }
+    const registeredTypes = new Set((0, registry_1.getRegisteredConnectionTypes)());
+    const connections = { kind: 'dict', entries: {} };
+    for (const [name, rawEntry] of Object.entries(value)) {
+        const prefix = `connections.${name}`;
+        if (!isRecord(rawEntry)) {
+            log.push(makeWarning(prefix, 'should be an object'));
+            continue;
+        }
+        const is = rawEntry['is'];
+        if (is === undefined || is === null || is === '') {
+            log.push(makeWarning(prefix, 'missing required "is" field (connection type)'));
+            continue;
+        }
+        if (typeof is !== 'string') {
+            log.push(makeWarning(`${prefix}.is`, '"is" should be a string'));
+            continue;
+        }
+        if (!registeredTypes.has(is)) {
+            const suggestion = closestMatch(is, [...registeredTypes]);
+            const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
+            log.push(makeWarning(`${prefix}.is`, `unknown connection type "${is}".${hint} Available types: ${[...registeredTypes].join(', ')}`));
+            continue;
+        }
+        const entry = compileConnectionEntry(prefix, is, rawEntry, log);
+        connections.entries[name] = entry;
+    }
+    return connections;
+}
+function compileConnectionEntry(prefix, typeName, rawEntry, log) {
+    var _a;
+    const props = (_a = (0, registry_1.getConnectionProperties)(typeName)) !== null && _a !== void 0 ? _a : [];
+    const propMap = new Map(props.map(p => [p.name, p]));
+    const entry = { kind: 'dict', entries: {} };
+    // Record the connection type as a plain value.
+    entry.entries['is'] = { kind: 'value', value: typeName };
+    for (const [key, value] of Object.entries(rawEntry)) {
+        if (key === 'is')
+            continue;
+        const propDef = propMap.get(key);
+        if (!propDef) {
+            const suggestion = closestMatch(key, [...propMap.keys()]);
+            const hint = suggestion ? `. Did you mean "${suggestion}"?` : '';
+            log.push(makeWarning(`${prefix}.${key}`, `unknown property "${key}" for connection type "${typeName}"${hint}`));
+            continue;
+        }
+        const node = compileConnectionProperty(`${prefix}.${key}`, propDef, value, log);
+        if (node !== undefined) {
+            entry.entries[key] = node;
+        }
+    }
+    return entry;
+}
+/**
+ * Compile a single connection property value. At non-`json` property slots,
+ * a single-key object whose value is a string or string[] is recognized as
+ * an overlay reference. `json`-typed slots always pass through as literal
+ * data — this is the security invariant that prevents reference injection
+ * into structured config.
+ */
+function compileConnectionProperty(path, propDef, value, log) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (propDef.type === 'json') {
+        return { kind: 'value', value };
+    }
+    const ref = asReferenceShape(value);
+    if (ref !== undefined) {
+        return ref;
+    }
+    const typeError = checkValueType(value, propDef.type);
+    if (typeError) {
+        log.push(makeWarning(path, `${typeError} (expected ${propDef.type})`));
+        return undefined;
+    }
+    return { kind: 'value', value };
+}
+// =============================================================================
+// Pass-through sections
+// =============================================================================
+function compileManifestPath(value, log) {
+    if (typeof value !== 'string') {
+        log.push(makeWarning('manifestPath', '"manifestPath" should be a string'));
+        return undefined;
+    }
+    return { kind: 'value', value };
+}
+function compileVirtualMap(value, _log) {
+    // virtualMap is a literal dict slot — no reference expansion, even if
+    // entries happen to look reference-shaped. The resolver will convert the
+    // plain structure into the runtime `VirtualMap` representation.
+    return { kind: 'value', value };
+}
+function compileIncludeDefaultConnections(value, _log) {
+    return { kind: 'value', value };
+}
+// =============================================================================
+// Reference-shape detection
+// =============================================================================
+/**
+ * Inspect a raw POJO value for the "overlay reference" shape: a single-key
+ * object whose value is a string (scalar path) or string[] (nested path).
+ * Returns a ConfigReference node if it matches, otherwise undefined.
+ *
+ * The single-key constraint distinguishes references from literal objects.
+ * This is a runtime invariant — TypeScript can't express "exactly one key".
+ */
+function asReferenceShape(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== 1)
+        return undefined;
+    const source = keys[0];
+    const inner = value[source];
+    if (typeof inner === 'string') {
+        return { kind: 'reference', source, path: [inner] };
+    }
+    if (Array.isArray(inner) && inner.every(x => typeof x === 'string')) {
+        return { kind: 'reference', source, path: inner };
+    }
+    return undefined;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function makeWarning(path, message) {
+    return {
+        message: `${path}: ${message}`,
+        severity: 'warn',
+        code: 'config-validation',
+    };
+}
+function checkValueType(value, expectedType) {
+    switch (expectedType) {
+        case 'number':
+            if (typeof value !== 'number')
+                return `should be a number, got ${typeof value}`;
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                return `should be a boolean, got ${typeof value}`;
+            break;
+        case 'string':
+        case 'password':
+        case 'secret':
+        case 'file':
+        case 'text':
+            if (typeof value !== 'string')
+                return `should be a string, got ${typeof value}`;
+            break;
+        case 'json':
+            break;
+    }
+    return undefined;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+function closestMatch(input, candidates) {
+    if (candidates.length === 0)
+        return undefined;
+    let best = candidates[0];
+    let bestDist = Infinity;
+    for (const c of candidates) {
+        const dist = levenshtein(input.toLowerCase(), c.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = c;
+        }
+    }
+    const maxDist = Math.max(1, Math.floor(Math.max(input.length, best.length) / 3));
+    return bestDist <= maxDist ? best : undefined;
+}
+//# sourceMappingURL=config_compile.js.map

package/dist/api/foundation/config_discover.d.ts

@@ -0,0 +1,37 @@
+import type { URLReader } from '../../runtime_types';
+import { MalloyConfig } from './config';
+import type { ConfigOverlays } from './config_overlays';
+/**
+ * Walk upward from `startURL` toward `ceilingURL`, looking for a
+ * `malloy-config.json` (or `malloy-config-local.json`) at each directory
+ * level. On a hit, build a `MalloyConfig` from the parsed POJO with a
+ * `config` overlay carrying `rootDirectory` (the ceiling) and `configURL`
+ * (the actual location of the file that matched). Returns `null` if no
+ * config file is found between `startURL` and `ceilingURL` (inclusive).
+ *
+ * `ceilingURL` is the host-supplied project root — discovery stops at that
+ * level, and it is what `config.rootDirectory` binds to in the typical
+ * overlay wiring. The matched config file's actual location rides on
+ * `config.configURL` so that `MalloyConfig.manifestURL` can resolve
+ * `MANIFESTS/malloy-manifest.json` relative to the file the config came
+ * from (not the project root).
+ *
+ * Callers can inspect what discovery found via `readOverlay` on the
+ * returned config:
+ *
+ *   const config = await discoverConfig(startURL, ceilingURL, urlReader);
+ *   config?.readOverlay('config', 'rootDirectory')  // the ceiling URL
+ *   config?.readOverlay('config', 'configURL')       // the matched file URL
+ *
+ * Hosts that want to layer additional overlays on top of discovery's
+ * `config` overlay (e.g. a `session` overlay for per-request data) pass
+ * them via `extraOverlays`. The merge is plain object-spread: extras with
+ * the same key as discovery's entries replace them wholesale. In
+ * particular, passing `{config: myConfigOverlay}` will clobber the
+ * `rootDirectory` + `configURL` discovery built — callers who want to
+ * extend discovery's `config` should read the keys back off and re-include
+ * them, or skip `discoverConfig` and build `MalloyConfig` directly.
+ *
+ * URL-based, so it works in browser-safe environments through `URLReader`.
+ */
+export declare function discoverConfig(startURL: URL, ceilingURL: URL, urlReader: URLReader, extraOverlays?: ConfigOverlays): Promise<MalloyConfig | null>;

package/dist/api/foundation/config_discover.js

@@ -0,0 +1,133 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverConfig = discoverConfig;
+const config_1 = require("./config");
+const config_overlays_1 = require("./config_overlays");
+const SHARED_FILENAME = 'malloy-config.json';
+const LOCAL_FILENAME = 'malloy-config-local.json';
+/**
+ * Walk upward from `startURL` toward `ceilingURL`, looking for a
+ * `malloy-config.json` (or `malloy-config-local.json`) at each directory
+ * level. On a hit, build a `MalloyConfig` from the parsed POJO with a
+ * `config` overlay carrying `rootDirectory` (the ceiling) and `configURL`
+ * (the actual location of the file that matched). Returns `null` if no
+ * config file is found between `startURL` and `ceilingURL` (inclusive).
+ *
+ * `ceilingURL` is the host-supplied project root — discovery stops at that
+ * level, and it is what `config.rootDirectory` binds to in the typical
+ * overlay wiring. The matched config file's actual location rides on
+ * `config.configURL` so that `MalloyConfig.manifestURL` can resolve
+ * `MANIFESTS/malloy-manifest.json` relative to the file the config came
+ * from (not the project root).
+ *
+ * Callers can inspect what discovery found via `readOverlay` on the
+ * returned config:
+ *
+ *   const config = await discoverConfig(startURL, ceilingURL, urlReader);
+ *   config?.readOverlay('config', 'rootDirectory')  // the ceiling URL
+ *   config?.readOverlay('config', 'configURL')       // the matched file URL
+ *
+ * Hosts that want to layer additional overlays on top of discovery's
+ * `config` overlay (e.g. a `session` overlay for per-request data) pass
+ * them via `extraOverlays`. The merge is plain object-spread: extras with
+ * the same key as discovery's entries replace them wholesale. In
+ * particular, passing `{config: myConfigOverlay}` will clobber the
+ * `rootDirectory` + `configURL` discovery built — callers who want to
+ * extend discovery's `config` should read the keys back off and re-include
+ * them, or skip `discoverConfig` and build `MalloyConfig` directly.
+ *
+ * URL-based, so it works in browser-safe environments through `URLReader`.
+ */
+async function discoverConfig(startURL, ceilingURL, urlReader, extraOverlays) {
+    // Normalize both to directory form.
+    let current = new URL('.', startURL);
+    const ceiling = new URL('.', ceilingURL);
+    // If we're not under (or at) the ceiling, there's nothing meaningful to
+    // walk — bail.
+    if (!isWithinOrEqual(current, ceiling))
+        return null;
+    for (;;) {
+        const found = await tryReadAtLevel(current, urlReader);
+        if (found)
+            return buildConfig(found, ceilingURL, extraOverlays);
+        if (current.toString() === ceiling.toString())
+            break;
+        const parent = new URL('..', current);
+        // URL scheme roots (`file:///`, `http://host/`) return themselves when
+        // you ask for their parent. Guard against the loop.
+        if (parent.toString() === current.toString())
+            break;
+        current = parent;
+    }
+    return null;
+}
+function buildConfig(hit, ceilingURL, extraOverlays) {
+    const discoveryOverlays = {
+        config: (0, config_overlays_1.contextOverlay)({
+            rootDirectory: ceilingURL.toString(),
+            configURL: hit.configURL.toString(),
+        }),
+    };
+    const merged = { ...discoveryOverlays, ...extraOverlays };
+    return new config_1.MalloyConfig(hit.pojo, merged);
+}
+async function tryReadAtLevel(dirURL, urlReader) {
+    const sharedURL = new URL(SHARED_FILENAME, dirURL);
+    const localURL = new URL(LOCAL_FILENAME, dirURL);
+    const [sharedPOJO, localPOJO] = await Promise.all([
+        tryReadJSON(sharedURL, urlReader),
+        tryReadJSON(localURL, urlReader),
+    ]);
+    // Local supersedes shared entirely when both exist — no merging of any
+    // kind. The person writing a local file is responsible for including
+    // everything they need.
+    if (localPOJO)
+        return { configURL: localURL, pojo: localPOJO };
+    if (sharedPOJO)
+        return { configURL: sharedURL, pojo: sharedPOJO };
+    return null;
+}
+/**
+ * Try to read and parse a config file at `url`.
+ *
+ * Two failure modes are distinguished:
+ *   - URL read fails (file not present) → returns `null`, signalling the
+ *     walker to keep going up.
+ *   - Read succeeds but contents are unparseable or not a JSON object →
+ *     throws. A matched-but-broken config file is a hard error; silently
+ *     skipping it would hide user mistakes and quietly fall through to a
+ *     grandparent config.
+ */
+async function tryReadJSON(url, urlReader) {
+    let contents;
+    try {
+        const result = await urlReader.readURL(url);
+        contents = typeof result === 'string' ? result : result.contents;
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Malformed JSON in ${url.toString()}: ${msg}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`Config file ${url.toString()} must contain a JSON object at the top level`);
+    }
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isWithinOrEqual(child, ancestor) {
+    return child.toString().startsWith(ancestor.toString());
+}
+//# sourceMappingURL=config_discover.js.map

package/dist/api/foundation/config_overlays.d.ts

@@ -0,0 +1,54 @@
+/**
+ * An overlay is a lambda that takes a compiled reference path and returns
+ * a value (or undefined if the path is not present in the overlay source).
+ *
+ * The path is an array because references can address nested data:
+ *   {env: "HOME"}             -> path = ["HOME"]
+ *   {user: ["address", "zip"]} -> path = ["address", "zip"]
+ *
+ * Overlay values should resolve to ordinary JSON-compatible values.
+ */
+export type Overlay = (path: string[]) => unknown;
+/**
+ * A dict keyed by overlay name. A config reference like
+ * `{env: "PG_PASSWORD"}` is resolved by looking up `overlays["env"]` and
+ * calling it with `["PG_PASSWORD"]`.
+ *
+ * Hosts provide additional overlays by passing a partial dict to the
+ * `MalloyConfig` constructor. The constructor merges it onto the default
+ * overlays by plain object spread, giving three behaviors:
+ *
+ *   - Add:     {session: sessionFn}       — env and config stay, session added
+ *   - Replace: {config: myConfigFn}       — host replaces the default config
+ *   - Disable: {config: () => undefined}  — refs to {config: ...} drop
+ */
+export type ConfigOverlays = Record<string, Overlay>;
+/**
+ * Built-in `env` overlay: reads `process.env[path[0]]`.
+ *
+ * Hardened against missing `process` so `defaultConfigOverlays()` is safe
+ * to call from any runtime. In the browser or a worker with no process.env,
+ * `{env: "X"}` references resolve to "not present" (property dropped),
+ * symmetric with the no-op default `config` overlay. Browser hosts can
+ * still swap in their own `env` overlay if they want a different source.
+ */
+export declare function envOverlay(): Overlay;
+/**
+ * Helper that turns a plain dict into an overlay lambda. Used by hosts
+ * (and discovery wiring) to build a populated `config` overlay.
+ *
+ *   const overlays = {
+ *     config: contextOverlay({
+ *       rootDirectory: ceilingURL,
+ *       configURL: configURL,
+ *     }),
+ *   };
+ */
+export declare function contextOverlay(dict: Record<string, unknown>): Overlay;
+/**
+ * The default config overlays: `env` wired to process.env, and a no-op
+ * `config` overlay. Hosts that want discovery-populated context replace
+ * the `config` entry; soloists leave it alone and `{config: ...}` refs
+ * resolve to "not present".
+ */
+export declare function defaultConfigOverlays(): ConfigOverlays;

package/dist/api/foundation/config_overlays.js

@@ -0,0 +1,51 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envOverlay = envOverlay;
+exports.contextOverlay = contextOverlay;
+exports.defaultConfigOverlays = defaultConfigOverlays;
+/**
+ * Built-in `env` overlay: reads `process.env[path[0]]`.
+ *
+ * Hardened against missing `process` so `defaultConfigOverlays()` is safe
+ * to call from any runtime. In the browser or a worker with no process.env,
+ * `{env: "X"}` references resolve to "not present" (property dropped),
+ * symmetric with the no-op default `config` overlay. Browser hosts can
+ * still swap in their own `env` overlay if they want a different source.
+ */
+function envOverlay() {
+    if (typeof process === 'undefined' || !process.env) {
+        return () => undefined;
+    }
+    return path => process.env[path[0]];
+}
+/**
+ * Helper that turns a plain dict into an overlay lambda. Used by hosts
+ * (and discovery wiring) to build a populated `config` overlay.
+ *
+ *   const overlays = {
+ *     config: contextOverlay({
+ *       rootDirectory: ceilingURL,
+ *       configURL: configURL,
+ *     }),
+ *   };
+ */
+function contextOverlay(dict) {
+    return path => dict[path[0]];
+}
+/**
+ * The default config overlays: `env` wired to process.env, and a no-op
+ * `config` overlay. Hosts that want discovery-populated context replace
+ * the `config` entry; soloists leave it alone and `{config: ...}` refs
+ * resolve to "not present".
+ */
+function defaultConfigOverlays() {
+    return {
+        env: envOverlay(),
+        config: () => undefined,
+    };
+}
+//# sourceMappingURL=config_overlays.js.map

package/dist/api/foundation/config_resolve.d.ts

@@ -0,0 +1,49 @@
+import type { LogMessage } from '../../lang/parse-log';
+import type { ConnectionConfigEntry } from '../../connection/registry';
+import type { ConfigDict } from './config_compile';
+import type { ConfigOverlays } from './config_overlays';
+/**
+ * The shape the class body consumes: a plain POJO with the same top-level
+ * sections as the input, but with all references resolved and defaults
+ * applied. This is fed into the connection registry to build connections.
+ *
+ * `connections` uses the registry's `ConnectionConfigEntry` shape directly —
+ * a resolved entry is precisely what the registry consumes, so there's no
+ * reason to invent a local alias and cast across the boundary.
+ *
+ * Note: `includeDefaultConnections` is an input directive, not a resolved
+ * value — by the time `resolveConfig` returns, fabrication has already
+ * happened. It intentionally does not appear on this interface.
+ */
+export interface ResolvedConfig {
+    connections: Record<string, ConnectionConfigEntry>;
+    manifestPath?: string;
+    virtualMap?: unknown;
+}
+/**
+ * Walk a compiled tree against the overlay dict and produce a plain
+ * resolved POJO.
+ *
+ * Two distinct "defaults" mechanisms, deliberately separated:
+ *
+ *   1. **Property defaults** (`applyPropertyDefaults`) — fill in missing
+ *      properties on *every* connection entry, user-listed or fabricated.
+ *      This is a uniform per-property rule; there is no asymmetry between
+ *      explicit and auto-generated entries.
+ *
+ *   2. **`includeDefaultConnections`** (`fabricateMissingConnections`) —
+ *      fabricate a bare `{is: typeName}` entry for each registered backend
+ *      not already represented. Property defaults then fill in their
+ *      properties via (1).
+ *
+ *   Order matters: fabrication runs before property defaults so that
+ *   fabricated entries pick up defaults in the same pass as user-listed
+ *   ones.
+ *
+ * Three unresolved-reference cases, each with different handling:
+ *   1. Unknown overlay source    → warning, drop property
+ *   2. Known overlay → undefined → silent drop
+ *   3. Property default → unresolved (either of the above inside a default)
+ *                                → silent drop (a default is a hint, not a requirement)
+ */
+export declare function resolveConfig(compiled: ConfigDict, overlays: ConfigOverlays, log: LogMessage[]): ResolvedConfig;