@leuduan/block 0.0.0-stage → 3.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Duan Leu
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @leuduan/block
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SQL builder and renderer for GoogleSQL, in pipe syntax (`FROM t |> WHERE ...`) with standard `SELECT` available
+for CTEs and subqueries. TypeScript port of `dbox.block` (`py/dbox/dbox/block`). Pure functions over plain data:
+no I/O, no credentials, no dependencies. Rendered SQL text is the package's contract; it is not required to match
+the Python builder byte for byte.
+
+## Ownership
+
+The package owns the immutable query model (`QueryExpression`, `Pipe`, `TableExpression`), the line-breaking
+renderer (`l`, 120 columns by default) and the builders on top of it: `p` (pipes), `e` (expressions), `h` (clause
+helpers), `q` (queries), `t` (table expressions) and the `sql` tag, with `from` exported at the root. Every function
+has one name and one home; the namespaces export factories, not the concrete classes behind them. A pipe is applied
+one way: `pipe(query, p.where(...), ...)`. Pipe syntax is GoogleSQL's, so the result is a `GoogleSqlQuery`; applying
+pipes to one extends its own pipe list instead of nesting (reusable steps are a `Pipe[]` to spread into the call).
+Deliberate nesting is `q.googleQuery({ queryExpression, pipes })`. Pipes that take a list take an array. String
+literals (`e.literalString`, the typed date and time literals) and quoted identifiers (`e.ident`, `t.path(id, true)`)
+are escaped with GoogleSQL's backslash escapes.
+
+It also owns datasets: `define` declares one (a table, or a query whose `build` receives a `BuildContext`) and
+records its call site, `problemsOf` judges a definition, and `datasetBuilder` builds them. Every definition carries
+its own `id`, a path of names from the outermost namespace to the dataset (`['analytics', 'events']`), so a dataset
+keeps its name wherever its declaration lives; messages show it dotted, and no segment may contain a dot. A builder is
+one session that builds each
+(dataset, case) once: it refuses two datasets with one id, resolves parameter values from defaults and cases, keeps
+one value per parameter name across inlined queries, inlines references and refuses cycles, and returns the result graph
+(`BuiltDataset`: the query, its parameters, the results it referenced, the assets it loaded). A failure inside a
+referenced dataset is rethrown at the `ctx.ref` call with the original as its `cause`.
+
+It does not own table names, projects, asset files or what a query means. The builder takes them from the caller, with
+no defaults: `tableName` gives a table's fully-qualified name, `asset` loads an asset's SQL text. Policies over the
+built SQL, such as a rule against handwritten table ids or references outside a catalog (the result graph lists
+them), are the caller's too. Quoting is the caller's job as well: `from(string)` and `t.path(id, false)` emit the text as given, so use `t.path(id, true)` or
+`e.ident(name)` for identifiers. `create_table` and the ANSI dialect (`dbox.block.ansi`) are not ported.
+
+## Use
+
+```ts
+import { e, from, h, p, pipe, t } from '@leuduan/block'
+
+const duplicates = pipe(
+  from(t.path('my-project.analytics.events', true)),
+  p.select(['id', 'updated_at', 'value']),
+  p.extend([h.expression(e.call('count', ['distinct value']), 'distinct_values')]),
+  p.where('distinct_values > 1'),
+  p.orderBy(['id']),
+)
+
+duplicates.format() // FROM `my-project.analytics.events` |> SELECT ...
+```
+
+Datasets, built standalone:
+
+```ts
+import { Dataset, datasetBuilder, define, p, pipe, sql } from '@leuduan/block'
+
+const EVENTS = define({ kind: 'table', id: ['analytics', 'events'], description: 'Raw events.' })
+const recent = define({
+  kind: 'query',
+  id: ['analytics', 'recent_events'],
+  description: 'Events since a day.',
+  params: { day: { type: 'DATE', default: '2026-01-01' } },
+  build: (ctx) => pipe(ctx.ref(EVENTS), p.where(sql`day >= ${ctx.param('day')}`)),
+})
+
+const builder = datasetBuilder({
+  tableName: (dataset) => `my-project.${Dataset.definitionOf(dataset).id.join('.')}`,
+  asset: (file) => {
+    throw new Error(`no assets here: ${file}`)
+  },
+})
+const { query, parameters } = builder.build(recent, null) // parameters: [{ name: 'day', type: 'DATE', ... }]
+```
+
+## Development
+
+Run from the repository root:
+
+```sh
+pnpm -F @leuduan/block build
+pnpm -F @leuduan/block typecheck
+pnpm -F @leuduan/block test
+```
+
+`prepack` cleans and builds `dist/`. Publication is a separate operation.

package/dist/build.d.ts

@@ -0,0 +1,40 @@
+import { Dataset } from './descriptor.js';
+import type { ParamType, ParamValue } from './descriptor.js';
+import { QueryExpression } from './sql.js';
+/** A named query parameter as built: the SQL refers to `@name`. */
+export interface Parameter {
+    name: string;
+    type: ParamType;
+    value: ParamValue;
+}
+export interface BuildOptions {
+    /** The fully-qualified name of a table dataset. */
+    tableName(dataset: Dataset): string;
+    /** The SQL text of the asset `file` that `dataset`'s build asks for. */
+    asset(file: string, dataset: Dataset): string;
+}
+export interface BuiltDataset {
+    readonly dataset: Dataset;
+    /** `null` for parameter defaults, and always for a table. */
+    readonly case: string | null;
+    readonly query: QueryExpression;
+    /** The parameters the query uses, its references' included, sorted by name. */
+    readonly parameters: readonly Parameter[];
+    /** A table's name as `tableName` gave it; `null` for a query. */
+    readonly tableName: string | null;
+    /** What the build referenced directly, each result once, in the order of first reference. */
+    readonly refs: readonly BuiltDataset[];
+    /** The asset files the build loaded, as it named them. */
+    readonly assets: readonly string[];
+}
+export interface DatasetBuilder {
+    /**
+     * `dataset` built for `caseName` (`null` builds with the parameter defaults). Throws what stops the build: a
+     * blocking problem of a definition, an id another dataset of this session already has, a missing parameter value, a
+     * reference cycle, an error of a `build`. A failure
+     * inside a referenced dataset is rethrown at the `ctx.ref` call, its error as the `cause`.
+     */
+    build(dataset: Dataset, caseName: string | null): BuiltDataset;
+}
+export declare function datasetBuilder(options: BuildOptions): DatasetBuilder;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.js

@@ -0,0 +1,171 @@
+// Building declared datasets into queries and their named parameters. A builder is one session: it builds each
+// (dataset, case) once, so a dataset referenced from several places is one result. The caller decides what a table
+// is named and where assets come from; everything else about evaluating a definition is here.
+import { Dataset } from './descriptor.js';
+import { lit } from './line.js';
+import { problemsOf } from './problems.js';
+import { raw } from './query.js';
+import { QueryExpression, from } from './sql.js';
+import { path } from './t.js';
+/** The dotted form of a dataset's id: one string per dataset, since no segment contains a dot. */
+function idOf(dataset) {
+    return Dataset.definitionOf(dataset).id.join('.');
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function paramValues(definition, caseName) {
+    const values = new Map();
+    const bindings = caseName === null ? {} : (definition.cases?.[caseName] ?? {});
+    for (const [name, spec] of Object.entries(definition.params ?? {})) {
+        const value = (Object.hasOwn(bindings, name) ? bindings[name] : undefined) ?? spec.default;
+        if (value !== undefined)
+            values.set(name, { name, type: spec.type, value });
+    }
+    return values;
+}
+/** Inlined queries share one parameter namespace, so a name must mean one value wherever it is used. */
+function mergeParameters(into, parameters, origin) {
+    for (const parameter of parameters) {
+        const existing = into.get(parameter.name);
+        if (existing && (existing.type !== parameter.type || existing.value !== parameter.value)) {
+            throw new Error(`parameter @${parameter.name} gets different values here and in ${origin}`);
+        }
+        into.set(parameter.name, parameter);
+    }
+}
+export function datasetBuilder(options) {
+    const results = new Map();
+    const datasetsById = new Map();
+    const active = [];
+    function cached(dataset, caseName) {
+        return results.get(dataset)?.get(Dataset.definitionOf(dataset).kind === 'table' ? null : caseName);
+    }
+    /** `loop` runs from a reference's target to a dataset still being built. */
+    function cycleError(loop) {
+        const start = active.indexOf(loop[loop.length - 1]);
+        return new Error(`reference cycle: ${[...active.slice(start), ...loop].map(idOf).join(' -> ')}`);
+    }
+    /**
+     * The path from a result built earlier down to a dataset being built now, if there is one. A build that caught a
+     * failed reference can have succeeded with a loop in its references, so reusing its result must check them.
+     */
+    function pathToActive(result, visited) {
+        if (active.includes(result.dataset))
+            return [result.dataset];
+        visited.add(result);
+        for (const ref of result.refs) {
+            if (visited.has(ref))
+                continue;
+            const path = pathToActive(ref, visited);
+            if (path)
+                return [result.dataset, ...path];
+        }
+        return null;
+    }
+    function buildQuery(dataset, definition, caseName) {
+        if (caseName !== null && !Object.hasOwn(definition.cases ?? {}, caseName)) {
+            throw new Error(`no case "${caseName}"`);
+        }
+        const values = paramValues(definition, caseName);
+        const missing = Object.keys(definition.params ?? {}).filter((name) => !values.has(name));
+        if (missing.length > 0)
+            throw new Error(`parameters without a value (pass { case }): ${missing.join(', ')}`);
+        const parameters = new Map();
+        const refs = new Set();
+        const assets = new Set();
+        const query = definition.build({
+            ref(target, refOptions) {
+                if (!(target instanceof Dataset))
+                    throw new Error('ctx.ref needs a dataset');
+                const id = idOf(target);
+                if (active.includes(target))
+                    throw cycleError([target]);
+                const targetCase = refOptions?.case ?? null;
+                let child = cached(target, targetCase);
+                if (child) {
+                    const loop = pathToActive(child, new Set());
+                    if (loop)
+                        throw cycleError(loop);
+                }
+                else {
+                    try {
+                        child = build(target, targetCase);
+                    }
+                    catch (error) {
+                        throw new Error(`${id} does not render: ${messageOf(error)}`, { cause: error });
+                    }
+                }
+                mergeParameters(parameters, child.parameters, id);
+                refs.add(child);
+                return child.query;
+            },
+            param(name) {
+                const value = values.get(name);
+                if (!value)
+                    throw new Error(`unknown parameter "${name}"`);
+                mergeParameters(parameters, [value], 'a dataset it references');
+                return lit(`@${name}`);
+            },
+            asset(file) {
+                const text = options.asset(file, dataset);
+                assets.add(file);
+                return raw(text.replace(/[\s;]+$/, ''));
+            },
+        });
+        if (!(query instanceof QueryExpression))
+            throw new Error('build must return a block query');
+        return {
+            dataset,
+            case: caseName,
+            query,
+            parameters: [...parameters.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+            tableName: null,
+            refs: [...refs],
+            assets: [...assets],
+        };
+    }
+    function build(dataset, caseName) {
+        const definition = Dataset.definitionOf(dataset);
+        const key = definition.kind === 'table' ? null : caseName;
+        const memo = cached(dataset, key);
+        if (memo)
+            return memo;
+        const blocking = problemsOf(definition).find((problem) => problem.blocks);
+        if (blocking)
+            throw new Error(blocking.message);
+        const id = idOf(dataset);
+        const sameId = datasetsById.get(id);
+        if (sameId && sameId !== dataset)
+            throw new Error(`two datasets have the id "${id}"`);
+        datasetsById.set(id, dataset);
+        let result;
+        active.push(dataset);
+        try {
+            if (definition.kind === 'table') {
+                const tableName = options.tableName(dataset);
+                result = {
+                    dataset,
+                    case: null,
+                    query: from(path(tableName, true)),
+                    parameters: [],
+                    tableName,
+                    refs: [],
+                    assets: [],
+                };
+            }
+            else {
+                result = buildQuery(dataset, definition, key);
+            }
+        }
+        finally {
+            active.pop();
+        }
+        let byCase = results.get(dataset);
+        if (!byCase)
+            results.set(dataset, (byCase = new Map()));
+        byCase.set(key, result);
+        return result;
+    }
+    return { build };
+}

package/dist/define.d.ts

@@ -0,0 +1,8 @@
+import { Dataset } from './descriptor.js';
+import type { ParamsSpec, QueryDefinition, TableDefinition } from './descriptor.js';
+/**
+ * Declare a dataset: a table (`kind: 'table'`) or a derived query (`kind: 'query'`). The result is opaque, records
+ * the call site and nothing global.
+ */
+export declare function define<const P extends ParamsSpec = ParamsSpec>(definition: TableDefinition | QueryDefinition<P>): Dataset;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.js

@@ -0,0 +1,25 @@
+import { Dataset } from './descriptor.js';
+const PAREN_FRAME = /\((.+):(\d+):\d+\)$/;
+const BARE_FRAME = /^\s*at (.+):(\d+):\d+$/;
+/** Frames of the code that called `define`: V8's stack minus its header line, `callerFrames` and `define`. */
+function callerFrames() {
+    const options = Error;
+    const limit = options.stackTraceLimit;
+    options.stackTraceLimit = 40;
+    const stack = new Error().stack ?? '';
+    options.stackTraceLimit = limit;
+    const frames = [];
+    for (const line of stack.split('\n').slice(3)) {
+        const match = PAREN_FRAME.exec(line) ?? BARE_FRAME.exec(line);
+        if (match)
+            frames.push({ file: match[1], line: Number(match[2]) });
+    }
+    return frames;
+}
+/**
+ * Declare a dataset: a table (`kind: 'table'`) or a derived query (`kind: 'query'`). The result is opaque, records
+ * the call site and nothing global.
+ */
+export function define(definition) {
+    return new Dataset(definition, callerFrames());
+}

package/dist/descriptor.d.ts

@@ -0,0 +1,66 @@
+import type { Line } from './line.js';
+import type { QueryExpression } from './sql.js';
+export declare const PARAM_TYPES: readonly ['STRING', 'INT64', 'FLOAT64', 'BOOL', 'DATE', 'DATETIME', 'TIMESTAMP', 'TIME'];
+export type ParamType = (typeof PARAM_TYPES)[number];
+export type ParamValue = string | number | boolean;
+export interface ParamSpec {
+    type: ParamType;
+    default?: ParamValue;
+}
+export type ParamsSpec = Record<string, ParamSpec>;
+interface CommonDefinition {
+    /**
+     * Names the dataset wherever it is declared, so moving the declaration does not rename it. Segments run from the
+     * outermost namespace to the name; none contains a dot, so the dotted form in messages names one dataset.
+     */
+    id: readonly [string, ...string[]];
+    description: string;
+    /** Notes on what columns mean. Free text, never a schema. */
+    columns?: Record<string, string>;
+}
+export interface TableDefinition extends CommonDefinition {
+    kind: 'table';
+    /** Physical table name, for the builder's `tableName` to use. */
+    table?: string;
+    partitionedBy?: readonly string[];
+    clusteredBy?: readonly string[];
+}
+export interface BuildContext<Name extends string = string> {
+    /**
+     * A block query over another dataset. A table is `FROM` its name (the builder's `tableName`); a query is the
+     * referenced query itself, inlined, built with its parameter defaults or with `case`.
+     */
+    ref(dataset: Dataset, options?: {
+        case?: string;
+    }): QueryExpression;
+    /** The named query parameter `@name`; the build result carries its type and value. */
+    param(name: Name): Line;
+    /** The raw SQL of the asset `file` (the builder's `asset` loads it), minus a trailing semicolon. */
+    asset(file: string): QueryExpression;
+}
+export interface QueryDefinition<P extends ParamsSpec = ParamsSpec> extends CommonDefinition {
+    kind: 'query';
+    /** `'metric'` marks the canonical definition of a business measure. */
+    role?: 'metric';
+    /** Every parameter has a default, or every case binds it. */
+    params?: P;
+    /** Named parameter sets; each renders on its own. */
+    cases?: Record<string, {
+        [Name in keyof P]?: ParamValue;
+    }>;
+    build: (ctx: BuildContext<keyof P & string>) => QueryExpression;
+}
+export type Definition = TableDefinition | QueryDefinition;
+export interface Frame {
+    file: string;
+    line: number;
+}
+export declare class Dataset {
+    #private;
+    constructor(definition: Definition, frames: readonly Frame[]);
+    static definitionOf(dataset: Dataset): Definition;
+    /** The stack frames of the `define(...)` call, innermost first, `define`'s own frames removed. */
+    static framesOf(dataset: Dataset): readonly Frame[];
+}
+export {};
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/descriptor.js

@@ -0,0 +1,19 @@
+// The dataset descriptor `define(...)` returns: a table or a derived query, declared with notes and a `build` over
+// the query model. `datasetBuilder` builds it; `Dataset.definitionOf` and `Dataset.framesOf` are for callers that
+// check or locate declarations.
+export const PARAM_TYPES = ['STRING', 'INT64', 'FLOAT64', 'BOOL', 'DATE', 'DATETIME', 'TIMESTAMP', 'TIME'];
+export class Dataset {
+    #definition;
+    #frames;
+    constructor(definition, frames) {
+        this.#definition = definition;
+        this.#frames = frames;
+    }
+    static definitionOf(dataset) {
+        return dataset.#definition;
+    }
+    /** The stack frames of the `define(...)` call, innermost first, `define`'s own frames removed. */
+    static framesOf(dataset) {
+        return dataset.#frames;
+    }
+}

package/dist/expr.d.ts

@@ -0,0 +1,37 @@
+import { type Line, type LineOrStr } from './line.js';
+import { type QueryExpression } from './sql.js';
+export declare function compare(left: LineOrStr, right: LineOrStr, op?: string): Line;
+export declare function coalesce(args: readonly LineOrStr[]): Line;
+export declare function like(expr: LineOrStr, pattern: string, notLike?: boolean): Line;
+export declare function in_(e: LineOrStr, values: readonly (string | number | Line)[]): Line;
+export declare function cast(expr: LineOrStr, toType: string): Line;
+export declare function literalBool(value: boolean): Line;
+export declare function literalNumber(value: number): Line;
+export declare function literalString(value: string): Line;
+export declare function isNull(expr: LineOrStr, notNull?: boolean): Line;
+export declare function concat(args: readonly LineOrStr[]): Line;
+export declare function literalDate(value: Date | string): Line;
+export declare function literalDatetime(value: Date | string): Line;
+export declare function literalTime(value: Date | string): Line;
+export declare function date(expr: LineOrStr): Line;
+export declare function literalTimestamp(value: Date | string, timezone?: string): Line;
+export declare function timestamp(expr: LineOrStr): Line;
+export declare function call(func: LineOrStr, args: readonly LineOrStr[]): Line;
+export declare function if_(condition: LineOrStr, trueExpr: LineOrStr, falseExpr: LineOrStr): Line;
+export declare function struct(fields: readonly LineOrStr[]): Line;
+export declare function between(expr: LineOrStr, low: LineOrStr, high: LineOrStr, notBetween?: boolean): Line;
+export declare function not(expr: LineOrStr): Line;
+export declare function case_(opts: {
+    expr?: LineOrStr;
+    whens: readonly [LineOrStr, LineOrStr][];
+    elseExpr?: LineOrStr;
+}): Line;
+export declare function inSubquery(expr: LineOrStr, query: QueryExpression, notIn?: boolean): Line;
+export declare function or(exprs: readonly LineOrStr[]): Line;
+export declare function and(exprs: readonly LineOrStr[]): Line;
+export declare function star(excepts?: readonly LineOrStr[]): Line;
+/** Backtick-quoted GoogleSQL identifier; escaped like a string literal, so the name is exactly `name`. */
+export declare function ident(name: string): Line;
+export declare const TS_MIN: Line;
+export declare const TS_MAX: Line;
+//# sourceMappingURL=expr.d.ts.map

package/dist/expr.js

@@ -0,0 +1,159 @@
+// Port of py/dbox/dbox/block/expr.py
+// Scalar SQL expression helpers — all return Line.
+import * as l from './line.js';
+import {} from './line.js';
+import {} from './sql.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/**
+ * The one place a string becomes a quoted GoogleSQL token, a string literal or (with a backtick) a quoted
+ * identifier, which take the same escapes. GoogleSQL escapes with backslashes (a doubled quote is not an escape), so
+ * `\`, the delimiter and every control character are escaped and the token has exactly the value of `value`. A
+ * string with a lone surrogate has no UTF-8 form and is refused.
+ */
+function quoteString(value, quote = "'") {
+    if (LONE_SURROGATE.test(value))
+        throw new Error('A string with a lone surrogate cannot be a GoogleSQL literal');
+    let body = '';
+    for (const ch of value) {
+        if (ch === '\\' || ch === quote)
+            body += '\\' + ch;
+        else if (ch === '\n')
+            body += '\\n';
+        else if (ch === '\r')
+            body += '\\r';
+        else if (ch === '\t')
+            body += '\\t';
+        else if (ch < ' ' || ch === '\x7f')
+            body += '\\x' + ch.charCodeAt(0).toString(16).padStart(2, '0');
+        else
+            body += ch;
+    }
+    return quote + body + quote;
+}
+// ---------------------------------------------------------------------------
+// Public expression helpers
+// ---------------------------------------------------------------------------
+export function compare(left, right, op = '=') {
+    return l.ladder([l.ensure(left), l.lit(op), l.ensure(right)]);
+}
+export function coalesce(args) {
+    return call(l.keyword('COALESCE'), args);
+}
+export function like(expr, pattern, notLike = false) {
+    return l.threeway([l.ensure(expr), l.keyword(notLike ? 'NOT LIKE' : 'LIKE'), literalString(pattern)]);
+}
+export function in_(e, values) {
+    const allStr = values.length > 0 && values.every((v) => typeof v === 'string');
+    const allNum = values.length > 0 && values.every((v) => typeof v === 'number');
+    const vLines = allStr
+        ? values.map((v) => literalString(v))
+        : allNum
+            ? values.map((v) => literalNumber(v))
+            : values.map((v) => l.ensure(v));
+    return l.ladder([l.ensure(e), l.keyword('IN'), l.paren(l.stackComma(vLines))]);
+}
+export function cast(expr, toType) {
+    return l.callLike({ call: l.keyword('CAST'), line: l.stack([l.ensure(expr), l.keyword(`AS ${toType}`)]) });
+}
+export function literalBool(value) {
+    return l.lit(value ? 'TRUE' : 'FALSE');
+}
+export function literalNumber(value) {
+    return l.lit(String(value));
+}
+export function literalString(value) {
+    return l.lit(quoteString(value));
+}
+export function isNull(expr, notNull = false) {
+    return l.indentNext([l.ensure(expr), l.keyword(notNull ? 'IS NOT NULL' : 'IS NULL')]);
+}
+export function concat(args) {
+    return call(l.keyword('CONCAT'), args);
+}
+export function literalDate(value) {
+    const s = typeof value === 'string' ? value : value.toISOString().slice(0, 10);
+    return l.lit(`DATE ${quoteString(s)}`);
+}
+export function literalDatetime(value) {
+    const s = typeof value === 'string' ? value : value.toISOString().replace('T', ' ').replace('Z', '');
+    return l.lit(`DATETIME ${quoteString(s)}`);
+}
+export function literalTime(value) {
+    const s = typeof value === 'string' ? value : value.toISOString().slice(11, 19);
+    return l.lit(`TIME ${quoteString(s)}`);
+}
+export function date(expr) {
+    return call(l.keyword('DATE'), [expr]);
+}
+export function literalTimestamp(value, timezone) {
+    const s = typeof value === 'string' ? value : value.toISOString().replace('T', ' ').replace('Z', '');
+    if (timezone !== undefined) {
+        return call('timestamp', [l.lit(quoteString(s)), l.lit(quoteString(timezone))]);
+    }
+    return l.combine([l.keyword('TIMESTAMP'), l.lit(quoteString(s))]);
+}
+export function timestamp(expr) {
+    return call(l.keyword('TIMESTAMP'), [expr]);
+}
+export function call(func, args) {
+    return l.callLike({ call: l.ensure(func), line: l.stackComma(args.map((a) => l.ensure(a))) });
+}
+export function if_(condition, trueExpr, falseExpr) {
+    return call(l.keyword('IF'), [condition, trueExpr, falseExpr]);
+}
+export function struct(fields) {
+    return call(l.keyword('STRUCT'), fields);
+}
+export function between(expr, low, high, notBetween = false) {
+    return l.indentNext([
+        l.ensure(expr),
+        l.indentNext([
+            l.keyword(notBetween ? 'NOT BETWEEN' : 'BETWEEN'),
+            l.stack([l.ensure(low), l.keyword('AND'), l.ensure(high)]),
+        ]),
+    ]);
+}
+export function not(expr) {
+    return l.indentNext([l.keyword('NOT'), l.ensure(expr)]);
+}
+export function case_(opts) {
+    const whenLines = opts.whens.map(([matchExpr, result]) => l.stack([
+        l.indentNext([l.keyword('when'), l.ensure(matchExpr)]),
+        l.indentNext([l.keyword('then'), l.ensure(result)]),
+    ]));
+    return l.indentMid([
+        l.indentNext([l.keyword('case'), opts.expr !== undefined ? l.ensure(opts.expr) : null]),
+        l.stack(whenLines),
+        opts.elseExpr !== undefined ? l.indentNext([l.keyword('else'), l.ensure(opts.elseExpr)]) : null,
+        l.keyword('end'),
+    ]);
+}
+export function inSubquery(expr, query, notIn = false) {
+    return l.indentNext([
+        l.stack([l.ensure(expr), l.keyword(notIn ? 'NOT IN' : 'IN')]),
+        query.toTableExpression().toLine(),
+    ]);
+}
+export function or(exprs) {
+    return l.stackBinOp(exprs.map((e) => l.ensure(e)), l.keyword('OR'));
+}
+export function and(exprs) {
+    return l.stackBinOp(exprs.map((e) => l.ensure(e)), l.keyword('AND'));
+}
+export function star(excepts = []) {
+    if (excepts.length === 0)
+        return l.lit('*');
+    return l.callLike({ call: l.lit('* EXCEPT'), line: l.stackComma(excepts.map((e) => l.ensure(e))) });
+}
+/** Backtick-quoted GoogleSQL identifier; escaped like a string literal, so the name is exactly `name`. */
+export function ident(name) {
+    return l.lit(quoteString(name, '`'));
+}
+// ---------------------------------------------------------------------------
+// Timestamp extremes
+// ---------------------------------------------------------------------------
+export const TS_MIN = l.keyword('TIMESTAMP "1900-01-01 00:00:00.000000 UTC"');
+export const TS_MAX = l.keyword('TIMESTAMP "9999-12-31 23:59:59.999999 UTC"');

package/dist/helpers.d.ts

@@ -0,0 +1,28 @@
+import { type Line, type LineOrStr } from './line.js';
+import { type QueryExpression, type MapOrRecord } from './sql.js';
+/** Build WITH / |> WITH clause from a ctes mapping (insertion-order preserved). */
+export declare function ctes(ctesMap: MapOrRecord<QueryExpression>, opts?: {
+    withPipe?: boolean;
+}): Line;
+export declare function array(elements: readonly LineOrStr[]): Line;
+/**
+ * Wrap an expression with an optional alias.
+ * Uses combine([keyword("AS"), lit(alias)]) — matching helpers.py:29.
+ */
+export declare function expression(expr: LineOrStr, alias?: string): Line;
+export declare function analytic(expr: LineOrStr, window?: LineOrStr): Line;
+export declare function window(partitionBy: readonly LineOrStr[], orderBy?: readonly LineOrStr[]): Line;
+export declare function set(name: string, value: LineOrStr): Line;
+export declare function desc(expr: LineOrStr): Line;
+export declare function asc(expr: LineOrStr): Line;
+/** Build "name AS (query)" — used for CTE-like subquery aliases. */
+export declare function aliasSubquery(name: string, query: LineOrStr): Line;
+/** Build "SELECT AS STRUCT col1, col2, ..." line fragment. */
+export declare function selectAsStruct(columns: readonly string[]): Line;
+/** UNNEST expression with optional alias. */
+export declare function unnest(source: LineOrStr, alias?: string): Line;
+/** Build STRUCT<field1, field2, ...> type expression. */
+export declare function structType(fields: readonly LineOrStr[] | MapOrRecord<LineOrStr>): Line;
+/** Build "WINDOW name AS (window_def), ..." clause. */
+export declare function windows(windowsMap: MapOrRecord<LineOrStr>): Line;
+//# sourceMappingURL=helpers.d.ts.map