@malloydata/malloy 0.0.372 → 0.0.373

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

@@ -1,51 +1,37 @@
-import type { URLReader } from '../../runtime_types';
 import type { Connection, LookupConnection } from '../../connection/types';
-import type { ConnectionConfigEntry } from '../../connection/registry';
 import type { LogMessage } from '../../lang/parse-log';
 import type { BuildID, BuildManifest, BuildManifestEntry, VirtualMap } from '../../model/malloy_types';
-/**
- * The parsed contents of a malloy-config.json file.
- */
-export interface MalloyProjectConfig {
-    connections?: Record<string, ConnectionConfigEntry>;
-    manifestPath?: string;
-    virtualMap?: VirtualMap;
-}
+import type { ConfigOverlays } from './config_overlays';
 /**
  * In-memory manifest store. Reads, updates, and serializes manifest data.
  *
- * Always valid — starts empty, call load() to populate from a file.
- * The BuildManifest object returned by `buildManifest` is stable: load()
- * and update() mutate the same entries object, so any reference obtained
- * via `buildManifest` stays current without re-assignment.
+ * Always valid — starts empty. Populate by calling `loadText(jsonText)` with
+ * the manifest file contents, which the caller reads themselves (typically
+ * through a `URLReader` they already have). The `Manifest` class deliberately
+ * does no IO — it exists so that applications that want to build or mutate
+ * manifest state have a typed handle with a stable `buildManifest` reference.
  *
- * The `strict` flag controls what happens when a persist source's BuildID
- * is not found in the manifest. When strict, the compiler throws an error
- * instead of falling through to inline SQL. The flag is loaded from the
- * manifest file and can be overridden by the application before creating
- * a Runtime.
+ * The `BuildManifest` returned by `buildManifest` is stable: `loadText()` and
+ * `update()` mutate the same entries object, so any reference obtained via
+ * `buildManifest` stays current without re-assignment.
+ *
+ * The `strict` flag controls what happens when a persist source's BuildID is
+ * not found in the manifest. When strict, the compiler throws an error
+ * instead of falling through to inline SQL. Loaded from the manifest file by
+ * `loadText()`; applications may override it at any time.
  */
 export declare class Manifest {
-    private readonly _urlReader?;
     private readonly _manifest;
     private readonly _touched;
-    constructor(urlReader?: URLReader);
-    /**
-     * Load manifest data from a manifest root directory.
-     * Reads `<manifestRoot>/malloy-manifest.json` via the URLReader.
-     * Replaces any existing data. If the file doesn't exist or no URLReader
-     * is available, clears to empty.
-     */
-    load(manifestRoot: URL): Promise<void>;
     /**
      * Load manifest data from a JSON string.
      * Replaces any existing data.
      */
     loadText(jsonText: string): void;
     /**
-     * The live BuildManifest. This is a stable reference — load() and update()
-     * mutate the same object, so passing this to a Runtime means the Runtime
-     * always sees current data including the strict flag.
+     * The live BuildManifest. This is a stable reference — `loadText()` and
+     * `update()` mutate the same object, so passing this to a Runtime means
+     * the Runtime always sees current data including the strict flag.
      */
     get buildManifest(): BuildManifest;
     /**
@@ -73,97 +59,112 @@ export declare class Manifest {
     private _loadParsed;
 }
 /**
- * Loads and holds a Malloy project configuration (connections + manifest +
- * virtualMap). Pass directly to Runtime — everything flows automatically.
+ * A resolved Malloy runtime configuration. The constructor takes either a
+ * JSON string (legacy/compat) or a POJO plus an optional `ConfigOverlays`
+ * dict, compiles the input into a typed tree, resolves all overlay
+ * references, and builds the connection lookup via the connection registry.
  *
- *   // From a URL — reads config + manifest via URLReader
- *   const config = new MalloyConfig(urlReader, configURL);
- *   await config.load();
+ * After construction:
+ *   - `connections` — the `LookupConnection` runtime consumes. Starts as the
+ *     lookup created from the resolved connections; `wrapConnections()` replaces
+ *     it with a wrapped version for host-specific behavior.
+ *   - `virtualMap` — extracted from the POJO as-is.
+ *   - `manifestPath` — extracted from the POJO as-is (the raw string).
+ *   - `manifestURL` — resolved URL of `malloy-manifest.json`, computed from
+ *     `manifestPath` + the `configURL` carried on the `config` overlay (if
+ *     any). `undefined` when no `configURL` is available. Runtime uses this
+ *     to lazily read the manifest on the first persistence query. Builders
+ *     that want to construct or mutate manifest state use the standalone
+ *     `Manifest` class directly — they don't go through MalloyConfig.
+ *   - `log` — validation warnings and overlay-resolution warnings.
  *
- *   // From text you already have
- *   const config = new MalloyConfig(configText);
+ * Typical usage:
  *
- *   // Either way, pass to Runtime — connections, buildManifest, virtualMap
- *   // all come from the config. No manual wiring needed.
+ *   // From a pre-loaded POJO (e.g. from `discoverConfig` or Publisher):
+ *   const config = new MalloyConfig(pojo);
  *   const runtime = new Runtime({config, urlReader});
  *
- * To override specific fields, mutate the config before passing:
- *   config.connectionMap = myCustomConnections;
+ *   // From a JSON string:
+ *   const config = new MalloyConfig(configText);
+ *
+ *   // With host-supplied overlays (local hosts after discovery):
+ *   const config = new MalloyConfig(pojo, {
+ *     config: contextOverlay({rootDirectory: ceilingURL}),
+ *   });
+ *
+ *   // Wrap the connection lookup for host-specific behavior:
+ *   config.wrapConnections(base => name => base(name) ?? fallback(name));
+ *
+ * The old async `new MalloyConfig(urlReader, configURL)` form has been
+ * removed. Callers that need to load from a URL should pre-load via
+ * `urlReader.readURL()` / `JSON.parse()` and pass the POJO, or use the
+ * sync string form after reading the file.
  */
 export declare class MalloyConfig {
-    private readonly _urlReader?;
-    private readonly _configURL?;
-    private _data;
-    private _log;
-    private _connectionMap;
-    private readonly _manifest;
-    private _managedLookup;
-    private _connectionLookupOverride;
-    private _onConnectionCreated;
-    constructor(configText: string);
-    constructor(urlReader: URLReader, configURL: string);
-    /**
-     * Load everything: parse config file, then load the default manifest.
-     * No-op if created from text.
-     */
-    load(): Promise<void>;
-    /**
-     * Load only the config file. Does not load the manifest.
-     * No-op if created from text.
-     */
-    loadConfig(): Promise<void>;
-    /**
-     * The parsed config data. Undefined if created from URL and not yet loaded.
+    readonly virtualMap?: VirtualMap;
+    readonly manifestPath?: string;
+    /**
+     * Resolved URL of the manifest file (`malloy-manifest.json`), if a
+     * `configURL` was provided in the `config` overlay. Computed once in the
+     * constructor from `manifestPath` (default `'MANIFESTS'`) joined to
+     * `configURL`. Stays `undefined` for callers that didn't supply a
+     * `configURL` — Runtime treats that as "no auto-read."
+     */
+    readonly manifestURL?: URL;
+    readonly log: readonly LogMessage[];
+    private _connections;
+    private readonly _managedLookup;
+    private readonly _overlays;
+    constructor(source: string);
+    constructor(pojo: object, overlays?: ConfigOverlays);
+    /**
+     * The live `LookupConnection` consumed by Runtime. Stable until
+     * `wrapConnections()` is called; after that, returns the wrapped lookup.
      */
-    get data(): MalloyProjectConfig | undefined;
+    get connections(): LookupConnection<Connection>;
     /**
-     * The active connection entries. Set this to override which connections
-     * are used before constructing a Runtime.
+     * Wrap the current connection lookup with a host-supplied wrapper.
+     * Mutates in place — subsequent `connections` accesses return the new
+     * wrapped lookup. Runtime never needs to know whether wrapping happened.
+     *
+     * Typical uses:
+     *   - VS Code layers settings + defaults below the config lookup
+     *   - Publisher attaches session-specific behavior to resolved connections
      */
-    get connectionMap(): Record<string, ConnectionConfigEntry> | undefined;
-    set connectionMap(map: Record<string, ConnectionConfigEntry>);
+    wrapConnections(wrapper: (base: LookupConnection<Connection>) => LookupConnection<Connection>): void;
     /**
-     * A LookupConnection built from the current connectionMap via the
-     * connection type registry. The result is cached — repeated access
-     * returns the same object (and the same underlying connections).
+     * Notify every connection this config has handed out that it is time to
+     * release its resources, then drop them from the internal cache.
      *
-     * If `connectionLookup` has been set, returns the override instead.
+     * Most callers should use `Runtime.releaseConnections()` instead — the
+     * expected contract is one MalloyConfig per Runtime, and the runtime is
+     * the natural handle for lifecycle. This method exists because Runtime
+     * forwards to it, and for the rare case of a MalloyConfig constructed
+     * without an accompanying Runtime.
      *
-     * Changing `connectionMap` invalidates the cache; the next access
-     * creates a fresh ManagedConnectionLookup.
-     */
-    get connections(): LookupConnection<Connection>;
-    /**
-     * Override the connection lookup entirely. When set, the `connections`
-     * getter returns this instead of building from `connectionMap`.
-     * Use this when you need to merge config connections with other sources.
-     */
-    get connectionLookup(): LookupConnection<Connection> | undefined;
-    set connectionLookup(lookup: LookupConnection<Connection> | undefined);
-    /**
-     * Callback invoked once per connection immediately after factory creation.
-     * Use for post-creation setup (e.g., registering WASM file handlers).
-     * Must be set before the first connection is looked up.
-     */
-    set onConnectionCreated(cb: ((name: string, connection: Connection) => void) | undefined);
-    /**
-     * Close all connections created by this config's internal managed lookup.
-     * Does nothing if connections were overridden via `connectionLookup`.
-     */
-    close(): Promise<void>;
-    /**
-     * The Manifest object. Always exists, may be empty if not yet loaded.
-     */
-    get manifest(): Manifest;
-    /**
-     * The VirtualMap parsed from config, if present.
+     * MalloyConfig does not own any connection resources itself — pools,
+     * sockets, file handles, and in-process databases all live inside the
+     * individual Connection objects. What the managed lookup owns is a cache
+     * of `name → Connection` populated lazily as callers request connections.
+     * This method walks that cache and calls `Connection.close()` on each
+     * entry, which is the signal each connection uses to shut down whatever
+     * resources it actually holds.
+     *
+     * Connections that were never looked up were never constructed and have
+     * nothing to release; they are skipped. Wrapping lookups installed via
+     * `wrapConnections()` do not interfere — the managed lookup under the
+     * wrap is the one holding the cache.
      */
-    get virtualMap(): VirtualMap | undefined;
+    releaseConnections(): Promise<void>;
     /**
-     * Errors and warnings from parsing and validating the config.
-     * Includes JSON parse errors (severity 'error') and schema validation
-     * warnings (severity 'warn') such as unknown keys, unknown connection
-     * types, wrong value types, and missing environment variables.
+     * Query a value from the overlays used to resolve this config.
+     *
+     * Returns the value the named overlay produces for the given path,
+     * or `undefined` if the overlay doesn't exist or the path has no value.
+     *
+     *   config.readOverlay('config', 'rootDirectory')
+     *   config.readOverlay('config', 'configURL')
+     *   config.readOverlay('env', 'PG_PASSWORD')
      */
-    get log(): LogMessage[];
+    readOverlay(overlayName: string, ...path: string[]): unknown;
 }