@terascope/data-mate 2.24.0 → 2.25.1

package/dist/src/teal-frame/extensions-cli.js

@@ -0,0 +1,56 @@
+/* eslint-disable no-console */
+// This CLI runs as an image build step and reports to the build log, so it writes to the
+// console directly.
+import { parseArgs } from 'node:util';
+import { installExtensions, verifyExtensions } from './extension-tools.js';
+const USAGE = `usage: duckdb-extensions <install|verify> [--dir <directory>] [--repository <url|dir>]
+
+  install   download the extensions TealFrame needs into --dir (run at image build time)
+  verify    check they load and work without network access (run in the final image)
+
+  --dir         defaults to $DUCKDB_EXTENSION_DIRECTORY, then ~/.duckdb/extensions
+  --repository  install only: an internal mirror, laid out as
+                <repository>/<duckdb version>/<platform>/<name>.duckdb_extension.gz
+
+Exits non-zero on any failure, so a build step running it fails the build.`;
+async function main() {
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        options: {
+            dir: { type: 'string' },
+            repository: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const [command] = positionals;
+    if (values.help || (command !== 'install' && command !== 'verify') || positionals.length > 1) {
+        console.error(USAGE);
+        return values.help ? 0 : 2;
+    }
+    if (command === 'verify' && values.repository != null) {
+        console.error('--repository applies to install only; verify never uses the network');
+        return 2;
+    }
+    const report = command === 'install'
+        ? await installExtensions({ directory: values.dir, repository: values.repository })
+        : await verifyExtensions({ directory: values.dir });
+    return print(command, report);
+}
+function print(command, report) {
+    const where = `duckdb ${report.version} on ${report.platform}, ${report.directory}`;
+    if (report.failures.length > 0) {
+        console.error(`duckdb-extensions ${command} FAILED (${where}):`);
+        for (const failure of report.failures)
+            console.error(`  ${failure}`);
+        return 1;
+    }
+    console.log(`duckdb-extensions ${command} ok (${where})`);
+    return 0;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    console.error('duckdb-extensions failed:', err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=extensions-cli.js.map

package/dist/src/teal-frame/extensions-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions-cli.js","sourceRoot":"","sources":["../../../src/teal-frame/extensions-cli.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,yFAAyF;AACzF,oBAAoB;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAmB,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,MAAM,KAAK,GAAG;;;;;;;;;2EAS6D,CAAC;AAE5E,KAAK,UAAU,IAAI;IACf,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QACtC,gBAAgB,EAAE,IAAI;QACtB,OAAO,EAAE;YACL,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACvB,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC9B,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;SACxC;KACJ,CAAC,CAAC;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,WAAW,CAAC;IAE9B,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ,CAAC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3F,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;QACpD,OAAO,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACrF,OAAO,CAAC,CAAC;IACb,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,KAAK,SAAS;QAChC,CAAC,CAAC,MAAM,iBAAiB,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QACnF,CAAC,CAAC,MAAM,gBAAgB,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAExD,OAAO,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,KAAK,CAAC,OAAe,EAAE,MAAuB;IACnD,MAAM,KAAK,GAAG,UAAU,MAAM,CAAC,OAAO,OAAO,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;IAEpF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,qBAAqB,OAAO,YAAY,KAAK,IAAI,CAAC,CAAC;QACjE,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,CAAC,KAAK,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QACrE,OAAO,CAAC,CAAC;IACb,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,qBAAqB,OAAO,QAAQ,KAAK,GAAG,CAAC,CAAC;IAC1D,OAAO,CAAC,CAAC;AACb,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACP,CAAC,IAAI,EAAE,EAAE;IACL,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC5B,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;IACb,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACrF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACzB,CAAC,CACJ,CAAC"}

package/dist/src/teal-frame/extensions.d.ts

@@ -0,0 +1,53 @@
+import { DuckDBConnection } from '@duckdb/node-api';
+/**
+ * The DuckDB extensions a frame needs, and how the database loads them.
+ *
+ * DuckDB downloads extensions from `extensions.duckdb.org` the first time a query needs one;
+ * no npm install step fetches them. Without network access that download fails at the first
+ * query that needs the extension rather than at startup. So every database loads them up front
+ * (`loadExtensions`), and images install them at build time (`extension-tools.ts`, run from
+ * `bin/duckdb-extensions.js`).
+ *
+ * parquet, json and icu are compiled into the binding (`STATIC_EXTENSIONS`). The four below
+ * are not. `spatial` does not autoload at all: without it, `ST_Point` is a catalog error.
+*/
+export interface DuckExtension {
+    readonly name: string;
+    /** What breaks without it, for the error a missing one produces. */
+    readonly reason: string;
+    /** Statements run by `verify` to check that the extension actually works. */
+    readonly check: readonly string[];
+}
+export declare const REQUIRED_EXTENSIONS: readonly DuckExtension[];
+/**
+ * Extensions compiled into the binding, which must never be installed: `INSTALL parquet`
+ * downloads a copy that shadows the built-in one and makes `duckdb_extensions()` misreport it.
+ * `install` checks they are still compiled in, so a DuckDB upgrade that drops one fails the build.
+*/
+export declare const STATIC_EXTENSIONS: readonly string[];
+/** Where the extensions live. Unset means DuckDB's default, `~/.duckdb/extensions`. */
+export declare const EXTENSION_DIRECTORY_ENV = "DUCKDB_EXTENSION_DIRECTORY";
+/** Set to `false` in an image, so a missing extension fails at startup instead of downloading. */
+export declare const AUTOINSTALL_EXTENSIONS_ENV = "DUCKDB_AUTOINSTALL_EXTENSIONS";
+export interface ExtensionSettings {
+    extensionDirectory?: string;
+    autoinstallExtensions?: boolean;
+}
+/**
+ * Reads the extension settings from the environment.
+ *
+ * They are read from the environment, not only from `configureDuckDatabase`, because the
+ * database may be opened by a frame before any configuration runs, and the directory must be
+ * correct from the moment it opens.
+*/
+export declare function extensionSettingsFromEnv(env?: NodeJS.ProcessEnv): ExtensionSettings;
+/**
+ * Loads every required extension and throws one error naming all that are missing.
+ *
+ * With autoinstall on (the default, used in local development) a missing extension is installed
+ * first, once per machine. With it off (in an image) nothing uses the network. Loading an
+ * already-loaded extension is cheap, so calling this again is harmless.
+*/
+export declare function loadExtensions(connection: DuckDBConnection, autoinstall: boolean): Promise<void>;
+export declare function firstLine(err: unknown): string;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/src/teal-frame/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIpD;;;;;;;;;;;EAWE;AAEF,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,mBAAmB,EAAE,SAAS,aAAa,EA2BvD,CAAC;AAEF;;;;EAIE;AACF,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAA+B,CAAC;AAE/E,uFAAuF;AACvF,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,kCAAkC,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;EAME;AACF,wBAAgB,wBAAwB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACrC,iBAAiB,CAUnB;AAUD;;;;;;EAME;AACF,wBAAsB,cAAc,CAChC,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,OAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAwBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAG9C"}

package/dist/src/teal-frame/extensions.js

@@ -0,0 +1,110 @@
+import { DuckExtensionError } from './errors.js';
+export const REQUIRED_EXTENSIONS = [
+    {
+        name: 'httpfs',
+        reason: 's3:// and https:// reads, and CREATE SECRET',
+        check: [
+            `CREATE OR REPLACE TEMPORARY SECRET duck_verify_httpfs (TYPE s3, KEY_ID 'verify', SECRET 'verify')`,
+            'DROP TEMPORARY SECRET duck_verify_httpfs',
+        ],
+    },
+    {
+        name: 'aws',
+        reason: 'the S3 credential chain (IAM and instance roles)',
+        check: [
+            `CREATE OR REPLACE TEMPORARY SECRET duck_verify_aws (TYPE s3, PROVIDER credential_chain, CHAIN 'env', VALIDATION 'none')`,
+            'DROP TEMPORARY SECRET duck_verify_aws',
+        ],
+    },
+    {
+        name: 'inet',
+        reason: 'the SQL form of the IP functions',
+        check: [`SELECT '1.2.3.4'::INET`],
+    },
+    {
+        name: 'spatial',
+        reason: 'the SQL form of the geo functions, which have no JavaScript fallback',
+        check: ['SELECT ST_AsText(ST_Point(1, 2))'],
+    },
+];
+/**
+ * Extensions compiled into the binding, which must never be installed: `INSTALL parquet`
+ * downloads a copy that shadows the built-in one and makes `duckdb_extensions()` misreport it.
+ * `install` checks they are still compiled in, so a DuckDB upgrade that drops one fails the build.
+*/
+export const STATIC_EXTENSIONS = ['icu', 'json', 'parquet'];
+/** Where the extensions live. Unset means DuckDB's default, `~/.duckdb/extensions`. */
+export const EXTENSION_DIRECTORY_ENV = 'DUCKDB_EXTENSION_DIRECTORY';
+/** Set to `false` in an image, so a missing extension fails at startup instead of downloading. */
+export const AUTOINSTALL_EXTENSIONS_ENV = 'DUCKDB_AUTOINSTALL_EXTENSIONS';
+/**
+ * Reads the extension settings from the environment.
+ *
+ * They are read from the environment, not only from `configureDuckDatabase`, because the
+ * database may be opened by a frame before any configuration runs, and the directory must be
+ * correct from the moment it opens.
+*/
+export function extensionSettingsFromEnv(env = process.env) {
+    const directory = env[EXTENSION_DIRECTORY_ENV]?.trim();
+    const autoinstall = parseBoolean(AUTOINSTALL_EXTENSIONS_ENV, env[AUTOINSTALL_EXTENSIONS_ENV]);
+    return {
+        ...(directory && { extensionDirectory: directory }),
+        ...(autoinstall != null && { autoinstallExtensions: autoinstall }),
+    };
+}
+function parseBoolean(name, raw) {
+    const value = raw?.trim().toLowerCase();
+    if (!value)
+        return undefined;
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    throw new TypeError(`${name} must be true or false, got "${raw}"`);
+}
+/**
+ * Loads every required extension and throws one error naming all that are missing.
+ *
+ * With autoinstall on (the default, used in local development) a missing extension is installed
+ * first, once per machine. With it off (in an image) nothing uses the network. Loading an
+ * already-loaded extension is cheap, so calling this again is harmless.
+*/
+export async function loadExtensions(connection, autoinstall) {
+    const missing = [];
+    for (const extension of REQUIRED_EXTENSIONS) {
+        const failure = await loadOne(connection, extension.name, autoinstall);
+        if (failure)
+            missing.push({ ...extension, error: failure });
+    }
+    if (missing.length === 0)
+        return;
+    const [[version, platform, directory]] = (await (await connection.run(`SELECT version(), (SELECT platform FROM pragma_platform()),`
+        + ` current_setting('extension_directory')`)).getRowsJson());
+    throw new DuckExtensionError({
+        missing, version, platform, directory: directory || '~/.duckdb/extensions', autoinstall,
+    });
+}
+/** Loads one extension. Returns the failure message, or undefined on success. */
+async function loadOne(connection, name, autoinstall) {
+    try {
+        await connection.run(`LOAD ${name}`);
+        return undefined;
+    }
+    catch (err) {
+        if (!autoinstall)
+            return firstLine(err);
+    }
+    try {
+        await connection.run(`INSTALL ${name}`);
+        await connection.run(`LOAD ${name}`);
+        return undefined;
+    }
+    catch (err) {
+        return firstLine(err);
+    }
+}
+export function firstLine(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.split('\n')[0];
+}
+//# sourceMappingURL=extensions.js.map

package/dist/src/teal-frame/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../../src/teal-frame/extensions.ts"],"names":[],"mappings":"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"}

package/dist/src/teal-frame/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TealFrame, a frame whose rows live in DuckDB.
+ *
+ * `DuckContext` is not exported, so a frame cannot be handed a database it cannot see. Use
+ * `configureDuckDatabase`, `registerScalarFunction` and `closeDuckDatabase` to manage the
+ * database.
+*/
+export * from './clauses.js';
+export * from './date-value.js';
+export * from './deep-select.js';
+export * from './database.js';
+export * from './TealFrame.js';
+export * from './duck-values.js';
+export * from './errors.js';
+export * from './expand-values.js';
+export * from './export-json.js';
+export * from './extension-tools.js';
+export * from './extensions.js';
+export * from './interfaces.js';
+export * from './scalar-function.js';
+export * from './udf-types.js';
+export * from './schema-check.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/teal-frame/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AACF,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC"}

package/dist/src/teal-frame/index.js

@@ -0,0 +1,23 @@
+/**
+ * TealFrame, a frame whose rows live in DuckDB.
+ *
+ * `DuckContext` is not exported, so a frame cannot be handed a database it cannot see. Use
+ * `configureDuckDatabase`, `registerScalarFunction` and `closeDuckDatabase` to manage the
+ * database.
+*/
+export * from './clauses.js';
+export * from './date-value.js';
+export * from './deep-select.js';
+export * from './database.js';
+export * from './TealFrame.js';
+export * from './duck-values.js';
+export * from './errors.js';
+export * from './expand-values.js';
+export * from './export-json.js';
+export * from './extension-tools.js';
+export * from './extensions.js';
+export * from './interfaces.js';
+export * from './scalar-function.js';
+export * from './udf-types.js';
+export * from './schema-check.js';
+//# sourceMappingURL=index.js.map

package/dist/src/teal-frame/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/teal-frame/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AACF,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC"}

package/dist/src/teal-frame/interfaces.d.ts

@@ -0,0 +1,186 @@
+import { DataTypeConfig, ReadonlyDataTypeConfig } from '@terascope/types';
+import { ValueConverter } from './duck-values.js';
+/**
+ * Option and result types for TealFrame and its database.
+*/
+/** A DataType configuration, however the caller happens to hold it. */
+export type FrameConfig = DataTypeConfig | ReadonlyDataTypeConfig;
+/** One field's coercion and its DuckDB value conversion, resolved once per append. */
+export interface FieldPlan {
+    name: string;
+    fieldType: string;
+    coerce: (value: unknown) => unknown;
+    convert: ValueConverter;
+}
+/** A freshly created table and the column set its config declared. */
+export interface CreatedTable {
+    table: string;
+    columns: string[];
+}
+/** Spill and resource settings for a database. All are runtime `SET`s. */
+export interface DuckDatabaseSettings {
+    /**
+     * Directory DuckDB spills to when a query exceeds `memoryLimit`. Without it, a query over
+     * the limit fails instead of spilling to disk.
+    */
+    tempDirectory?: string;
+    /** Cap on the spill directory, e.g. `'30GB'`. */
+    maxTempDirectorySize?: string;
+    /** DuckDB's memory limit, e.g. `'48GB'`. Set it below the container's memory cap. */
+    memoryLimit?: string;
+    threads?: number;
+    /**
+     * Where DuckDB looks for extensions. Defaults to `DUCKDB_EXTENSION_DIRECTORY`, then
+     * DuckDB's own `~/.duckdb/extensions`. It cannot be changed once the database is open,
+     * which is why the environment variable is the usual way to set it (see `extensions.ts`).
+    */
+    extensionDirectory?: string;
+    /**
+     * Whether a missing extension may be downloaded. Defaults to
+     * `DUCKDB_AUTOINSTALL_EXTENSIONS`, then true. A container image with bundled extensions
+     * sets it to false.
+    */
+    autoinstallExtensions?: boolean;
+}
+export interface DuckDatabaseOptions extends DuckDatabaseSettings {
+    /** A file path, or `:memory:`. See `FrameOptions.database` for how the string is read. */
+    database?: string;
+}
+/** Where a frame's rows come from. */
+export type Source = {
+    kind: 'table';
+    table: string;
+}
+/**
+ * `ordered` means the relation's rows come out in a defined order: it ends in an
+ * `ORDER BY`, or derives from one through an operator that preserves order. `join` and
+ * an aggregating `select` use it to refuse to discard that order silently; see
+ * `orderBy`. A table is never ordered, because nothing may rely on a table's row order.
+*/
+ | {
+    kind: 'relation';
+    sql: string;
+    ordered?: boolean;
+};
+/** One field's coercion failure, with the value that caused it. */
+export interface CoercionFailure {
+    field: string;
+    fieldType: string;
+    failedCount: number;
+    /** An original value that failed to convert. */
+    exampleValue: string;
+}
+export type CoercionMode = 'strict'
+/** For transforms: a value that fails to convert becomes null. */
+ | 'lenient';
+export interface FrameOptions {
+    /**
+     * Database path. Defaults to the process-wide `:memory:` database.
+     *
+     * Use it for a file-backed database or to give a test an isolated catalog. Frames in
+     * different databases cannot see each other's tables, so they cannot be joined.
+     *
+     * **Only the exact string `:memory:` is in-memory.** Anything else, including a bare name
+     * like `'my-test'` or the `:memory:<name>` form, is a file path and writes a database file.
+     * Tests rarely need this option: jest gives each test file its own module registry, and
+     * so its own default database.
+    */
+    database?: string;
+    /** Used for the table or relation name. */
+    name?: string;
+}
+export interface FromRecordsOptions extends FrameOptions {
+    /** Defaults to `strict`. */
+    mode?: CoercionMode;
+}
+/** Everything an append failure can say about itself. */
+export interface AppendFailure {
+    /** The table the rows were going into. */
+    table: string;
+    /** Which shape was being appended. */
+    source: 'records' | 'parquet';
+    /** What was being added, in words: `3 records`, or the paths. */
+    describedSource: string;
+    /**
+     * Rows in the table after the failed append, that is, the rows that survived. Counted only
+     * on failure, so a successful append does not pay for it. Undefined if the count itself
+     * failed, which means the table's state is unknown.
+    */
+    rowsRemaining?: number;
+}
+/**
+ * What to add to a frame: parsed records, or Parquet files. Both go through the one `append`
+ * method.
+*/
+export type AppendSource = {
+    records: readonly Record<string, unknown>[];
+    parquet?: never;
+}
+/** One path, a list of paths, or a glob. Already typed and validated, so not re-coerced. */
+ | {
+    parquet: string | readonly string[];
+    records?: never;
+};
+export interface AppendOptions {
+    /** Defaults to `strict`. Applies to records; Parquet is not coerced. */
+    mode?: CoercionMode;
+}
+/**
+ * A `SELECT` list, either as a map or as verbatim SQL.
+ *
+ * In the map form, `{ outputName: sqlExpression }`, the keys become the output column names.
+ * A string is used verbatim, as `QueryAccess.restrictSQLParts` returns it. That string cannot
+ * be turned into a map without losing the field restriction: the DuckDB dialect rebuilds a
+ * partly readable STRUCT with `struct_pack`, so its expressions and its `columns` do not
+ * correspond one to one.
+*/
+export type SelectList = string | Readonly<Record<string, string>>;
+/** Options for {@link TealFrame.select}. */
+export interface SelectOptions {
+    /** The result's declared field types. Defaults to the frame's own. */
+    config?: FrameConfig;
+    /** Group the rows, so project-then-aggregate is a single statement. */
+    groupBy?: readonly string[];
+    /** The result's column names, required when the `SELECT` list is verbatim. */
+    columns?: readonly string[];
+}
+/** How to join two frames. Expressions are raw SQL written against the two aliases. */
+export interface JoinOptions {
+    /** Join predicate, e.g. `'a.user_id = b.id'`. */
+    on: string;
+    /**
+     * Output expressions, `{ outputName: sqlExpression }`, or a `SELECT` list verbatim.
+     *
+     * Both sides are aliased, so a verbatim list joining two generated statements reads
+     * `'a.*, b."total"'`. The map form is the one to use when the two sides share column
+     * names, because a duplicate output name is a column the caller cannot read back.
+    */
+    select: SelectList;
+    /** The result's declared field types. The caller knows what its expressions produce. */
+    config: FrameConfig;
+    /** The result's column names, required when `select` is a verbatim list. */
+    columns?: readonly string[];
+    /** Defaults to `inner`. */
+    type?: 'inner' | 'left' | 'right' | 'full' | 'cross';
+    /** Alias for this frame. Defaults to `a`. */
+    as?: string;
+    /** Alias for the other frame. Defaults to `b`. */
+    otherAs?: string;
+    /** Group the joined rows, so join-then-aggregate is a single statement. */
+    groupBy?: readonly string[];
+}
+/** A required extension that could not be loaded, and DuckDB's reason. */
+export interface MissingExtension {
+    name: string;
+    reason: string;
+    error: string;
+}
+/** What `DuckExtensionError` reports: every missing extension, and where it looked. */
+export interface ExtensionFailure {
+    missing: readonly MissingExtension[];
+    version: string;
+    platform: string;
+    directory: string;
+    autoinstall: boolean;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/teal-frame/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/interfaces.ts"],"names":[],"mappings":"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"}

package/dist/src/teal-frame/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/src/teal-frame/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/teal-frame/interfaces.ts"],"names":[],"mappings":""}

package/dist/src/teal-frame/line-stream.d.ts

@@ -0,0 +1,10 @@
+/** Helpers over a stream of rendered JSON lines, shared by `ndjson`, `rows` and `writeNDJSON`. */
+/**
+ * Yields each distinct line once, in order. Backs `rowsWithoutDuplicates`, which compares
+ * whole rendered rows. Keeps every distinct line in memory.
+*/
+export declare function distinctLines(lines: AsyncIterable<string>): AsyncIterableIterator<string>;
+export declare function parseLines(lines: AsyncIterable<string>): AsyncIterableIterator<Record<string, unknown>>;
+/** Writes lines to a file, each followed by a newline, matching what `COPY` writes. */
+export declare function writeLines(path: string, lines: AsyncIterable<string>): Promise<void>;
+//# sourceMappingURL=line-stream.d.ts.map

package/dist/src/teal-frame/line-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-stream.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/line-stream.ts"],"names":[],"mappings":"AAGA,kGAAkG;AAElG;;;EAGE;AACF,wBAAuB,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAOhG;AAED,wBAAuB,UAAU,CAC7B,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAC7B,qBAAqB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEhD;AAED,uFAAuF;AACvF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1F"}

package/dist/src/teal-frame/line-stream.js

@@ -0,0 +1,35 @@
+import { createWriteStream } from 'node:fs';
+import { once } from 'node:events';
+/** Helpers over a stream of rendered JSON lines, shared by `ndjson`, `rows` and `writeNDJSON`. */
+/**
+ * Yields each distinct line once, in order. Backs `rowsWithoutDuplicates`, which compares
+ * whole rendered rows. Keeps every distinct line in memory.
+*/
+export async function* distinctLines(lines) {
+    const seen = new Set();
+    for await (const line of lines) {
+        if (seen.has(line))
+            continue;
+        seen.add(line);
+        yield line;
+    }
+}
+export async function* parseLines(lines) {
+    for await (const line of lines)
+        yield JSON.parse(line);
+}
+/** Writes lines to a file, each followed by a newline, matching what `COPY` writes. */
+export async function writeLines(path, lines) {
+    const out = createWriteStream(path);
+    try {
+        for await (const line of lines) {
+            if (!out.write(`${line}\n`))
+                await once(out, 'drain');
+        }
+    }
+    finally {
+        out.end();
+        await once(out, 'close');
+    }
+}
+//# sourceMappingURL=line-stream.js.map

package/dist/src/teal-frame/line-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-stream.js","sourceRoot":"","sources":["../../../src/teal-frame/line-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,kGAAkG;AAElG;;;EAGE;AACF,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,aAAa,CAAC,KAA4B;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,MAAM,IAAI,CAAC;IACf,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,UAAU,CAC7B,KAA4B;IAE5B,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;AACtF,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,KAA4B;IACvE,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC;QACD,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;gBAAE,MAAM,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;IACL,CAAC;YAAS,CAAC;QACP,GAAG,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC;AACL,CAAC"}

package/dist/src/teal-frame/order-safety.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Throws if an operation would silently discard the frame's ordering. Used by `TealFrame`'s
+ * `join`, `distinct` and aggregating `select`.
+ *
+ * SQL does not guarantee that a subquery's `ORDER BY` survives the outer query. In DuckDB a
+ * projection, `WHERE`, `LIMIT` or `OFFSET` keeps the order, but a hash join or hash aggregate
+ * reorders rows. This only shows once the data is large enough to run in parallel (small
+ * inputs come out ordered), so it is easy to miss in tests. Sort the result instead.
+ *
+ * A global aggregate written directly into `select`'s expressions with no `groupBy`
+ * (`{ total: 'sum(x)' }`) is not detected, because the expressions are raw SQL. It returns
+ * one row, so the ordering does not matter.
+*/
+export declare function assertOrderSafe(operation: string, ordered: boolean): void;
+//# sourceMappingURL=order-safety.d.ts.map

package/dist/src/teal-frame/order-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order-safety.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/order-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AACF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAQzE"}

package/dist/src/teal-frame/order-safety.js

@@ -0,0 +1,21 @@
+/**
+ * Throws if an operation would silently discard the frame's ordering. Used by `TealFrame`'s
+ * `join`, `distinct` and aggregating `select`.
+ *
+ * SQL does not guarantee that a subquery's `ORDER BY` survives the outer query. In DuckDB a
+ * projection, `WHERE`, `LIMIT` or `OFFSET` keeps the order, but a hash join or hash aggregate
+ * reorders rows. This only shows once the data is large enough to run in parallel (small
+ * inputs come out ordered), so it is easy to miss in tests. Sort the result instead.
+ *
+ * A global aggregate written directly into `select`'s expressions with no `groupBy`
+ * (`{ total: 'sum(x)' }`) is not detected, because the expressions are raw SQL. It returns
+ * one row, so the ordering does not matter.
+*/
+export function assertOrderSafe(operation, ordered) {
+    if (!ordered)
+        return;
+    throw new TypeError(`${operation} reorders rows, so this frame's ORDER BY would be silently discarded`
+        + ' (a join or GROUP BY does not preserve the order of its input once DuckDB runs it'
+        + ' in parallel). Sort the result instead.');
+}
+//# sourceMappingURL=order-safety.js.map

package/dist/src/teal-frame/order-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order-safety.js","sourceRoot":"","sources":["../../../src/teal-frame/order-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AACF,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,OAAgB;IAC/D,IAAI,CAAC,OAAO;QAAE,OAAO;IAErB,MAAM,IAAI,SAAS,CACf,GAAG,SAAS,sEAAsE;UAChF,mFAAmF;UACnF,yCAAyC,CAC9C,CAAC;AACN,CAAC"}

package/dist/src/teal-frame/output.d.ts

@@ -0,0 +1,18 @@
+import { DuckContext } from './DuckContext.js';
+import { JsonExportOptions } from './export-json.js';
+import { FrameConfig } from './interfaces.js';
+/**
+ * Implementations of `TealFrame`'s output methods: `writeParquet`, the JSON-lines query behind
+ * `ndjson`, `writeNDJSON` and `rows(options)`, and `listValues`. Their contracts are documented
+ * on `TealFrame`.
+*/
+/** Writes the frame to a zstd Parquet file, narrowing 128-bit columns to their declared type. */
+export declare function writeParquet(ctx: DuckContext, from: string, config: FrameConfig, path: string): Promise<void>;
+/**
+ * SQL that renders one JSON line per row, as `DataFrame.toJSON` does with the same options.
+ * Rows that `skipEmptyObjects` drops are filtered out. See `export-json.ts`.
+*/
+export declare function jsonLinesSQL(from: string, config: FrameConfig, options: JsonExportOptions): string;
+/** Yields one row's LIST column element by element, like `ListVector.getRowIterator`. */
+export declare function listValues(ctx: DuckContext, from: string, config: FrameConfig, column: string, options: JsonExportOptions): AsyncIterableIterator<unknown>;
+//# sourceMappingURL=output.d.ts.map

package/dist/src/teal-frame/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/output.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAC6D,iBAAiB,EAEpF,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;;;EAIE;AAEF,iGAAiG;AACjG,wBAAsB,YAAY,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;EAGE;AACF,wBAAgB,YAAY,CACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,iBAAiB,GAC3B,MAAM,CAIR;AAED,yFAAyF;AACzF,wBAAuB,UAAU,CAC7B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GAC3B,qBAAqB,CAAC,OAAO,CAAC,CA0BhC"}