@leuduan/block 0.0.0-stage → 3.0.0

package/dist/helpers.js

@@ -0,0 +1,98 @@
+// Port of py/dbox/dbox/block/helpers.py
+// Line-fragment helpers for common SQL constructs.
+import * as l from './line.js';
+import {} from './line.js';
+import { mapEntries } from './sql.js';
+// ---------------------------------------------------------------------------
+// CTE helpers
+// ---------------------------------------------------------------------------
+/** Build WITH / |> WITH clause from a ctes mapping (insertion-order preserved). */
+export function ctes(ctesMap, opts) {
+    const withPipe = opts?.withPipe ?? false;
+    const cteLines = mapEntries(ctesMap).map(([name, cte]) => aliasSubquery(name, cte.toLine()));
+    return l.indentNext([withPipe ? l.keyword('|> WITH') : l.keyword('WITH'), l.stackComma(cteLines)]);
+}
+// ---------------------------------------------------------------------------
+// Collection helpers
+// ---------------------------------------------------------------------------
+export function array(elements) {
+    return l.bracket(l.stackComma(elements.map((e) => l.ensure(e))));
+}
+// ---------------------------------------------------------------------------
+// Expression / column helpers
+// ---------------------------------------------------------------------------
+/**
+ * Wrap an expression with an optional alias.
+ * Uses combine([keyword("AS"), lit(alias)]) — matching helpers.py:29.
+ */
+export function expression(expr, alias) {
+    const exprLine = l.ensure(expr);
+    if (alias !== undefined) {
+        return l.indentNext([exprLine, l.combine([l.keyword('AS'), l.lit(alias)])]);
+    }
+    return exprLine;
+}
+export function analytic(expr, window) {
+    return l.indentNext([
+        l.ensure(expr),
+        window !== undefined ? l.callLike({ call: l.keyword('OVER'), line: l.ensure(window) }) : null,
+    ]);
+}
+export function window(partitionBy, orderBy = []) {
+    const partLine = partitionBy.length > 0
+        ? l.indentNext([l.keyword('PARTITION BY'), l.stackComma(partitionBy.map((p) => l.ensure(p)))])
+        : null;
+    const orderLine = orderBy.length > 0 ? l.indentNext([l.keyword('ORDER BY'), l.stackComma(orderBy.map((o) => l.ensure(o)))]) : null;
+    return l.stack([partLine, orderLine]);
+}
+export function set(name, value) {
+    return l.indentNext([l.lit(`${name} =`), l.ensure(value)]);
+}
+export function desc(expr) {
+    return l.stack([l.ensure(expr), l.keyword('DESC')]);
+}
+export function asc(expr) {
+    return l.stack([l.ensure(expr), l.keyword('ASC')]);
+}
+/** Build "name AS (query)" — used for CTE-like subquery aliases. */
+export function aliasSubquery(name, query) {
+    return l.callLike({
+        call: l.combine([l.lit(name), l.keyword('AS')]),
+        line: l.ensure(query),
+        sep: l.SPACE,
+    });
+}
+/** Build "SELECT AS STRUCT col1, col2, ..." line fragment. */
+export function selectAsStruct(columns) {
+    return l.indentNext([l.keyword('select as struct'), l.stackComma(columns.map((c) => l.ensure(c)))]);
+}
+/** UNNEST expression with optional alias. */
+export function unnest(source, alias) {
+    const inner = l.ensure(source);
+    let unnestExpr = l.callLike({ call: l.keyword('UNNEST'), line: inner });
+    if (alias !== undefined) {
+        unnestExpr = l.indentNext([unnestExpr, l.combine([l.keyword('AS'), l.lit(alias)])]);
+    }
+    return unnestExpr;
+}
+/** Build STRUCT<field1, field2, ...> type expression. */
+export function structType(fields) {
+    let fieldLines;
+    if (Array.isArray(fields)) {
+        fieldLines = fields.map((f) => l.ensure(f));
+    }
+    else {
+        // dict form: [{name: type}] → each becomes "name type"
+        fieldLines = mapEntries(fields).map(([k, v]) => l.indentNext([l.lit(k), l.ensure(v)]));
+    }
+    return l.wrap({
+        prefix: l.keyword('struct'),
+        wrapper: 'diamond',
+        line: l.stackComma(fieldLines),
+    });
+}
+/** Build "WINDOW name AS (window_def), ..." clause. */
+export function windows(windowsMap) {
+    const windowLines = mapEntries(windowsMap).map(([name, win]) => aliasSubquery(name, win));
+    return l.indentNext([l.keyword('WINDOW'), l.stackComma(windowLines)]);
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * as l from './line.js';
+export * as e from './expr.js';
+export * as h from './helpers.js';
+export * as p from './pipe.js';
+export * as q from './query.js';
+export * as t from './t.js';
+export type { Line, LineOrStr, Options } from './line.js';
+export { DEFAULT_OPTIONS } from './line.js';
+export type { SqlSegment, Pipe, TableExpression, GoogleSqlQuery } from './sql.js';
+export { QueryExpression, from, pipe, sql } from './sql.js';
+export { define } from './define.js';
+export { Dataset, PARAM_TYPES } from './descriptor.js';
+export { problemsOf } from './problems.js';
+export type { Problem } from './problems.js';
+export { datasetBuilder } from './build.js';
+export type { BuildOptions, BuiltDataset, DatasetBuilder, Parameter } from './build.js';
+export type { BuildContext, Definition, Frame, ParamSpec, ParamsSpec, ParamType, ParamValue, QueryDefinition, TableDefinition, } from './descriptor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,19 @@
+// Public entry of @leuduan/block, the GoogleSQL builder.
+// ---------------------------------------------------------------------------
+// Namespaces: l lines, e expressions, h clause helpers, p pipes, q queries, t table expressions
+// ---------------------------------------------------------------------------
+export * as l from './line.js';
+export * as e from './expr.js';
+export * as h from './helpers.js';
+export * as p from './pipe.js';
+export * as q from './query.js';
+export * as t from './t.js';
+export { DEFAULT_OPTIONS } from './line.js';
+export { QueryExpression, from, pipe, sql } from './sql.js';
+// ---------------------------------------------------------------------------
+// Dataset declarations and their build
+// ---------------------------------------------------------------------------
+export { define } from './define.js';
+export { Dataset, PARAM_TYPES } from './descriptor.js';
+export { problemsOf } from './problems.js';
+export { datasetBuilder } from './build.js';

package/dist/line.d.ts

@@ -0,0 +1,79 @@
+export declare const SPACE = " ";
+export declare const BLANK = "";
+export declare const NEWLINE = "\n";
+export declare const COMMA = ",";
+export declare const OPEN_PARENTHESIS = "(";
+export declare const CLOSE_PARENTHESIS = ")";
+export declare const OPEN_BRACKET = "[";
+export declare const CLOSE_BRACKET = "]";
+export declare const OPEN_CURLY_BRACE = "{";
+export declare const CLOSE_CURLY_BRACE = "}";
+export interface OptionsProps {
+    maxLength?: number;
+    keywordHandling?: 'upper_case' | 'lower_case';
+}
+export declare class Options {
+    readonly maxLength: number;
+    readonly keywordHandling: 'upper_case' | 'lower_case';
+    constructor(props?: OptionsProps);
+}
+export declare const DEFAULT_OPTIONS: Options;
+export interface ResultProps {
+    can?: boolean;
+    lines?: Line[];
+}
+export declare class Result {
+    readonly can: boolean;
+    readonly lines: Line[];
+    constructor(props?: ResultProps);
+}
+export type LineOrStr = Line | string;
+export declare abstract class Line {
+    abstract render(opt?: Options): string;
+    abstract get size(): number;
+    decompose(opt: Options): Result;
+}
+export declare function breakLine(line: Line, opt: Options, shouldBreak?: (line: Line) => boolean): Line[];
+export declare function formatLine(line: Line, opt: Options): string;
+export declare function lit(value: string): Line;
+export declare function keyword(name: string): Line;
+export declare function ensure(s: LineOrStr): Line;
+export declare function bracket(line: Line, sep?: string): Line;
+export declare function curlyBrace(line: Line | null, sep?: string): Line;
+export declare function callLike(opts: {
+    call: Line;
+    line: Line | null;
+    sep?: string;
+}): Line;
+export declare function wrap(opts: {
+    prefix: Line;
+    wrapper: 'paren' | 'bracket' | 'curly' | 'diamond';
+    line: Line;
+    wrapSep?: string;
+}): Line;
+export declare function combine(lines: ReadonlyArray<Line | null | undefined> | Line, opts?: {
+    sep?: string;
+}): Line;
+export declare function indent(line: Line, spaces?: number): Line;
+export declare function indentMid(lines: ReadonlyArray<Line | null | undefined>, sep?: string): Line;
+export declare function indentNext(lines: ReadonlyArray<Line | null | undefined>, sep?: string): Line;
+export declare function ladder(lines: ReadonlyArray<Line | null | undefined>): Line;
+export declare function multilineLiteral(content: string): Line;
+export declare function paren(line: Line | null, sep?: string): Line;
+export declare function stack(lines: ReadonlyArray<Line | null | undefined>, opts?: {
+    sep?: string;
+    forceBreak?: boolean;
+}): Line;
+export declare function stackComma(lines: ReadonlyArray<Line | null | undefined>): Line;
+export declare function stackCommaEnd(lines: ReadonlyArray<Line | null | undefined>): Line;
+export declare function stackWithSep(lines: ReadonlyArray<Line | null | undefined>, sep: Line): Line;
+export declare function stickySuffix(suffix: Line, line: Line, separator?: string): Line;
+export declare function threeway(lines: readonly Line[]): Line;
+export declare function stackBinOp(lines: readonly Line[], op: Line): Line;
+export declare const parenOpen: Line;
+export declare const parenClose: Line;
+export declare const bracketOpen: Line;
+export declare const bracketClose: Line;
+export declare const curlyBraceOpen: Line;
+export declare const curlyBraceClose: Line;
+//# sourceMappingURL=line.d.ts.map

package/dist/line.js

@@ -0,0 +1,450 @@
+// Port of py/dbox/dbox/block/line.py
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function todo(msg = '...') {
+    throw new Error(`TODO: ${msg}`);
+}
+// Mirrors Python str.splitlines(): splits on \r\n|\r|\n and drops a trailing
+// empty string ("a\n".splitlines() → ["a"], not ["a",""]).
+function splitlines(s) {
+    const parts = s.split(/\r\n|\r|\n/);
+    if (parts.length > 0 && parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+function removeNulls(lines) {
+    return lines.filter((l) => l != null);
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const SPACE = ' ';
+export const BLANK = '';
+export const NEWLINE = '\n';
+export const COMMA = ',';
+export const OPEN_PARENTHESIS = '(';
+export const CLOSE_PARENTHESIS = ')';
+export const OPEN_BRACKET = '[';
+export const CLOSE_BRACKET = ']';
+export const OPEN_CURLY_BRACE = '{';
+export const CLOSE_CURLY_BRACE = '}';
+export class Options {
+    maxLength;
+    keywordHandling;
+    constructor(props = {}) {
+        this.maxLength = props.maxLength ?? 120;
+        this.keywordHandling = props.keywordHandling ?? 'upper_case';
+    }
+}
+export const DEFAULT_OPTIONS = new Options();
+export class Result {
+    can;
+    lines;
+    constructor(props = {}) {
+        this.can = props.can ?? false;
+        this.lines = props.lines ?? [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Abstract base: Line
+// ---------------------------------------------------------------------------
+export class Line {
+    decompose(opt) {
+        return new Result({ can: false });
+    }
+}
+// ---------------------------------------------------------------------------
+// CacheLine — memoises size and decompose
+// ---------------------------------------------------------------------------
+class CacheLine extends Line {
+    forceBreak;
+    #cacheSize;
+    #cacheDecompose;
+    constructor(forceBreak = false) {
+        super();
+        this.forceBreak = forceBreak;
+    }
+    get size() {
+        if (this.forceBreak)
+            return 2 << 20;
+        if (this.#cacheSize === undefined) {
+            this.#cacheSize = this.sizeImpl;
+        }
+        return this.#cacheSize;
+    }
+    decompose(opt) {
+        if (this.#cacheDecompose === undefined) {
+            this.#cacheDecompose = this.decomposeImpl(opt);
+        }
+        return this.#cacheDecompose;
+    }
+}
+// ---------------------------------------------------------------------------
+// ComposableLine — joins child lines with a separator; subclasses own how it breaks
+// ---------------------------------------------------------------------------
+class ComposableLine extends CacheLine {
+    lines;
+    sep;
+    constructor(lines, sep = SPACE, forceBreak = false) {
+        super(forceBreak);
+        this.lines = lines;
+        this.sep = sep;
+    }
+    render(opt) {
+        return this.lines.map((line) => line.render(opt)).join(this.sep);
+    }
+    get sizeImpl() {
+        if (this.lines.length === 0)
+            return 0;
+        return this.lines.reduce((acc, line) => acc + line.size, 0) + this.sep.length * (this.lines.length - 1);
+    }
+}
+// ---------------------------------------------------------------------------
+// Concrete line classes (unexported — accessed only via factory functions)
+// ---------------------------------------------------------------------------
+class StackingLine extends ComposableLine {
+    decomposeImpl(opt) {
+        return new Result({ can: true, lines: [...this.lines] });
+    }
+}
+class Indented extends CacheLine {
+    indent;
+    line;
+    constructor(indentBy, line) {
+        super();
+        this.indent = indentBy;
+        this.line = line;
+    }
+    get sizeImpl() {
+        return this.indent + this.line.size;
+    }
+    render(opt) {
+        return SPACE.repeat(this.indent) + this.line.render(opt);
+    }
+    decomposeImpl(opt) {
+        const r = this.line.decompose(opt);
+        if (!r.can)
+            return new Result({ can: false });
+        return new Result({ can: true, lines: r.lines.map((l) => indent(l, this.indent)) });
+    }
+}
+class Ladder extends ComposableLine {
+    decomposeImpl(opt) {
+        return new Result({
+            can: true,
+            lines: this.lines.map((line, idx) => indent(line, idx * 2)),
+        });
+    }
+}
+class Threeway extends ComposableLine {
+    constructor(lines, sep = SPACE) {
+        if (lines.length !== 3)
+            throw new Error(`Threeway requires exactly 3 lines, got ${lines.length}`);
+        super(lines, sep);
+    }
+    decomposeImpl(opt) {
+        const first = this.lines[0];
+        const middle = this.lines[1];
+        const last = this.lines[2];
+        if (first.size <= last.size) {
+            return new Result({ can: true, lines: [stack([first, middle]), indent(last)] });
+        }
+        else {
+            return new Result({ can: true, lines: [first, indent(stack([middle, last]))] });
+        }
+    }
+}
+class IndentAfterFirst extends ComposableLine {
+    decomposeImpl(opt) {
+        if (this.lines.length === 0)
+            todo();
+        const first = this.lines[0];
+        const rest = this.lines.slice(1);
+        return new Result({
+            can: true,
+            lines: [first, ...rest.map((l) => indent(l, 2))],
+        });
+    }
+}
+class IndentMiddle extends ComposableLine {
+    decomposeImpl(opt) {
+        if (this.lines.length < 3)
+            todo();
+        const first = this.lines[0];
+        const middle = this.lines.slice(1, -1);
+        const last = this.lines[this.lines.length - 1];
+        return new Result({
+            can: true,
+            lines: [first, ...middle.map((l) => indent(l, 2)), last],
+        });
+    }
+}
+class StackingWithComma extends ComposableLine {
+    constructor(lines) {
+        super(lines, ', ');
+    }
+    decomposeImpl(opt) {
+        if (this.lines.length === 0)
+            todo();
+        const newLines = this.lines.map((line, idx) => (idx === 0 ? line : new CommaStartingLine(line)));
+        return new Result({ can: true, lines: newLines });
+    }
+}
+class NoBreak extends ComposableLine {
+    decomposeImpl(opt) {
+        return new Result({ can: false });
+    }
+}
+class Literal extends Line {
+    content;
+    isKeyword;
+    constructor(content, isKeyword = false) {
+        super();
+        this.content = content;
+        this.isKeyword = isKeyword;
+    }
+    get size() {
+        return this.content.length;
+    }
+    render(opt) {
+        if (this.isKeyword) {
+            if (opt && opt.keywordHandling === 'upper_case')
+                return this.content.toUpperCase();
+            if (opt && opt.keywordHandling === 'lower_case')
+                return this.content.toLowerCase();
+        }
+        return this.content;
+    }
+}
+class MultilineLiteral extends Line {
+    content;
+    constructor(content) {
+        super();
+        this.content = content;
+    }
+    get size() {
+        return 10000; // treat as infinite to force breaking
+    }
+    render(opt) {
+        return this.content;
+    }
+    decompose(opt) {
+        return new Result({ can: true, lines: splitlines(this.content).map((l) => lit(l)) });
+    }
+}
+class CommaStartingLine extends CacheLine {
+    line;
+    constructor(line) {
+        super();
+        this.line = line;
+    }
+    get sizeImpl() {
+        return 2 + this.line.size;
+    }
+    render(opt) {
+        return ', ' + this.line.render(opt);
+    }
+    decomposeImpl(opt) {
+        const r = this.line.decompose(opt);
+        if (!r.can)
+            return new Result({ can: false });
+        const first = r.lines[0];
+        const rest = r.lines.slice(1);
+        return new Result({ can: true, lines: [new CommaStartingLine(first), ...rest] });
+    }
+}
+class StickySuffix extends CacheLine {
+    suffix;
+    line;
+    separator;
+    constructor(suffix, line, separator = SPACE) {
+        super();
+        this.suffix = suffix;
+        this.line = line;
+        this.separator = separator;
+    }
+    get sizeImpl() {
+        return this.line.size + this.separator.length + this.suffix.size;
+    }
+    render(opt) {
+        return this.line.render(opt) + this.separator + this.suffix.render(opt);
+    }
+    decomposeImpl(opt) {
+        const r = this.line.decompose(opt);
+        if (!r.can)
+            return new Result({ can: false });
+        const lines = r.lines;
+        const last = lines[lines.length - 1];
+        return new Result({
+            can: true,
+            lines: [...lines.slice(0, -1), new StickySuffix(this.suffix, last, this.separator)],
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Core algorithm
+// ---------------------------------------------------------------------------
+export function breakLine(line, opt, shouldBreak) {
+    let lines = [line];
+    while (true) {
+        const newLines = [];
+        let canBreak = false;
+        for (const l of lines) {
+            if (l.size <= opt.maxLength && !(shouldBreak && shouldBreak(l))) {
+                newLines.push(l);
+                continue;
+            }
+            const r = l.decompose(opt);
+            if (r.can) {
+                canBreak = true;
+                newLines.push(...r.lines);
+            }
+            else {
+                newLines.push(l);
+            }
+        }
+        if (!canBreak)
+            break;
+        lines = newLines;
+    }
+    return lines;
+}
+export function formatLine(line, opt) {
+    return breakLine(line, opt)
+        .map((l) => l.render(opt))
+        .join(NEWLINE);
+}
+// ---------------------------------------------------------------------------
+// Factory functions
+// ---------------------------------------------------------------------------
+export function lit(value) {
+    return new Literal(value);
+}
+export function keyword(name) {
+    return new Literal(name, true);
+}
+export function ensure(s) {
+    if (s instanceof Line)
+        return s;
+    const str = String(s);
+    if (str.includes('\n'))
+        return multilineLiteral(str);
+    return lit(str);
+}
+export function bracket(line, sep = SPACE) {
+    return new IndentMiddle([bracketOpen, line, bracketClose], sep);
+}
+export function curlyBrace(line, sep = SPACE) {
+    if (line == null)
+        return lit(OPEN_CURLY_BRACE + CLOSE_CURLY_BRACE);
+    return new IndentMiddle([curlyBraceOpen, line, curlyBraceClose], sep);
+}
+export function callLike(opts) {
+    const sep = opts.sep ?? BLANK;
+    if (!opts.line) {
+        return combine([opts.call, parenOpen, parenClose], { sep });
+    }
+    return indentMid([combine([opts.call, parenOpen], { sep }), opts.line, parenClose], sep);
+}
+export function wrap(opts) {
+    const wrapSep = opts.wrapSep ?? SPACE;
+    let start;
+    let end;
+    if (opts.wrapper === 'paren') {
+        start = combine([opts.prefix, parenOpen], { sep: wrapSep });
+        end = parenClose;
+    }
+    else if (opts.wrapper === 'bracket') {
+        start = combine([opts.prefix, bracketOpen], { sep: wrapSep });
+        end = bracketClose;
+    }
+    else if (opts.wrapper === 'curly') {
+        start = combine([opts.prefix, curlyBraceOpen], { sep: wrapSep });
+        end = curlyBraceClose;
+    }
+    else if (opts.wrapper === 'diamond') {
+        start = combine([opts.prefix, lit('<')], { sep: wrapSep });
+        end = lit('>');
+    }
+    else {
+        throw new Error(`Unsupported wrapper: ${opts.wrapper}`);
+    }
+    return indentMid([start, opts.line, end], BLANK);
+}
+// Deviation from Python: `l_combine(line, *args, sep=SPACE)` varargs+keyword-sep
+// is not expressible in TS. TS signature: combine(lines | line, { sep }).
+export function combine(lines, opts) {
+    const sep = opts?.sep ?? SPACE;
+    const arr = lines instanceof Line ? [lines] : Array.from(lines);
+    return new NoBreak(removeNulls(arr), sep);
+}
+export function indent(line, spaces = 2) {
+    if (line instanceof Indented) {
+        return new Indented(line.indent + spaces, line.line);
+    }
+    return new Indented(spaces, line);
+}
+export function indentMid(lines, sep = SPACE) {
+    return new IndentMiddle(removeNulls(lines), sep);
+}
+export function indentNext(lines, sep = SPACE) {
+    return new IndentAfterFirst(removeNulls(lines), sep);
+}
+export function ladder(lines) {
+    return new Ladder(removeNulls(lines));
+}
+export function multilineLiteral(content) {
+    return new MultilineLiteral(content);
+}
+export function paren(line, sep = SPACE) {
+    if (line == null)
+        return lit(OPEN_PARENTHESIS + CLOSE_PARENTHESIS);
+    return new IndentMiddle([parenOpen, line, parenClose], sep);
+}
+export function stack(lines, opts) {
+    return new StackingLine(removeNulls(lines), opts?.sep ?? SPACE, opts?.forceBreak ?? false);
+}
+export function stackComma(lines) {
+    return new StackingWithComma(removeNulls(lines));
+}
+export function stackCommaEnd(lines) {
+    return stack(removeNulls(lines).map((line) => stickySuffix(lit(COMMA), line, BLANK)));
+}
+export function stackWithSep(lines, sep) {
+    const clean = removeNulls(lines);
+    if (clean.length === 0)
+        throw new Error('stackWithSep requires at least one line');
+    if (clean.length === 1)
+        return clean[0];
+    const first = clean[0];
+    const rest = clean.slice(1);
+    const interleaved = rest.reduce((acc, line) => [...acc, sep, line], [first]);
+    return stack(interleaved, { forceBreak: true });
+}
+export function stickySuffix(suffix, line, separator = SPACE) {
+    return new StickySuffix(suffix, line, separator);
+}
+export function threeway(lines) {
+    return new Threeway(lines);
+}
+export function stackBinOp(lines, op) {
+    if (lines.length === 0)
+        throw new Error('stackBinOp requires at least one line');
+    if (lines.length === 1)
+        return lines[0];
+    const first = lines[0];
+    const rest = lines.slice(1);
+    const tail = rest.reduce((acc, line) => [...acc, indentNext([op, line])], []);
+    return stack([first, ...tail]);
+}
+// ---------------------------------------------------------------------------
+// Pre-created singleton tokens
+// ---------------------------------------------------------------------------
+export const parenOpen = lit(OPEN_PARENTHESIS);
+export const parenClose = lit(CLOSE_PARENTHESIS);
+export const bracketOpen = lit(OPEN_BRACKET);
+export const bracketClose = lit(CLOSE_BRACKET);
+export const curlyBraceOpen = lit(OPEN_CURLY_BRACE);
+export const curlyBraceClose = lit(CLOSE_CURLY_BRACE);