data-finder-ts 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -1,22 +1,81 @@
-export { Attribute } from './datafinder/attribute.cjs';
+import { Attribute } from './datafinder/attribute.cjs';
 export { getRelatedFinderClass, registerRelatedFinderClass } from './datafinder/finder-registry.cjs';
-export { BooleanAttribute, DateAttribute, DateTimeAttribute, DecimalAttribute, DoubleAttribute, FloatAttribute, IntegerAttribute, NumericAttribute, StringAttribute } from './datafinder/typed-attributes.cjs';
+export { B as BooleanAttribute, D as DateAttribute, a as DateTimeAttribute, b as DecimalAttribute, c as DoubleAttribute, F as FloatAttribute, I as IntegerAttribute, N as NumericAttribute, d as NumericFunctionOperation, S as StringAttribute, e as StringFunctionOperation } from './typed-attributes-CdWXq_78.cjs';
+import { NumericConstantOperation, ConstantOperation, CountAllOperation, Operation, ExistsOperation, NotExistsOperation, RelationalOperationElement, CaseOperation, JoinTreeNodeOperation, SortOperation } from './model/relational.cjs';
+export { AggregateOperation, AggregateOperator, Aggregates, Alias, Aliasable, Arithmetic, ArithmeticOperand, ArithmeticOperation, ArithmeticOperator, BinaryOperation, BooleanAggregates, BooleanConstantOperation, Column, ColumnWithJoin, Comparable, ComparisonOperation, ComparisonOperator, ConcatOperation, ConcatPart, DATE_ONLY_PATTERN, DataCatalog, DataStore, Database, DateArithmeticOperation, DateConstantOperation, DateDiffOperation, DateExtractOperation, DateOnly, DatePart, DateTimeConstantOperation, DateTruncOperation, DecimalConstantOperation, FloatConstantOperation, ForeignKey, InOperation, IntegerConstantOperation, IsNotNullOperation, IsNullOperation, JoinOperation, LIKE_ESCAPE, LogicalOperation, LogicalOperator, NUMERIC_FUNCTIONS, NoOperation, NotInOperation, ScalarFunction, ScalarFunctionOperation, Schema, SelectOperation, SortDirection, Sortable, StringConstantOperation, StringPredicates, Table, UnaryOperation, WindowFunction, WindowFunctionOperation, WindowSpecification, applyMixins, concat, containsAggregate, containsAggregateOrWindow, escapeLike, operandOf, sample, valueOperand } from './model/relational.cjs';
 export { selectSqlToString, toSql } from './datafinder/sql-generator.cjs';
-import { RelationalOperationElement, JoinTreeNodeOperation, LogicalOperation } from './model/relational.cjs';
-export { AggregateOperation, AggregateOperator, BinaryOperation, BooleanConstantOperation, Column, ColumnWithJoin, ComparisonOperation, ComparisonOperator, ConstantOperation, CountAllOperation, DataCatalog, DataStore, Database, DateArithmeticOperation, DateConstantOperation, DateDiffOperation, DateExtractOperation, DatePart, DateTimeConstantOperation, DecimalConstantOperation, FloatConstantOperation, ForeignKey, IntegerConstantOperation, IsNotNullOperation, IsNullOperation, JoinOperation, LogicalOperator, NoOperation, Operation, ScalarFunction, ScalarFunctionOperation, Schema, SortDirection, SortOperation, StringConstantOperation, Table, UnaryOperation, WindowFunction, WindowFunctionOperation, WindowSpecification } from './model/relational.cjs';
-export { FinderResult, QueryRunner, QueryTarget, Row, clearRunner, convertInputsAndSelect, getRunner, registerRunner } from './datafinder/runner.cjs';
+export { D as DATABRICKS, a as DUCKDB, b as DialectName, P as POSTGRES, S as SqlDialect, d as dialectOf } from './dialect-CogGPm_y.cjs';
+import { QueryRunner, QueryTarget, Row } from './datafinder/runner.cjs';
+export { DEFAULT_TIMEOUT_MS, FinderResult, QueryTimeoutError, clearRunner, convertInputsAndSelect, convertInputsAndSelectForDateRange, getRunner, registerRunner } from './datafinder/runner.cjs';
 export { BiTemporalColumns, BusinessDateAndProcessingTemporalColumns, MilestonedTable, MilestoningColumns, ProcessingTemporalColumns, SingleBusinessDateColumn } from './model/milestoning.cjs';
 
-declare class ExistsOperation extends RelationalOperationElement {
-    readonly node: JoinTreeNodeOperation;
-    constructor(node: JoinTreeNodeOperation);
-    andOp(other: RelationalOperationElement): LogicalOperation;
+/** Expressions that are not a column of a finder: values to select next to the columns. */
+
+/**
+ * A fixed value as a column: `f.findAll(null, null, [f.name(), constant('EU').alias('Region')])`.
+ * A number is a `NumericConstantOperation`, which takes part in arithmetic: `constant(100).minus(f.price())`.
+ * A `DateOnly` is a date and any other `Date` a timestamp. It is named "Constant" unless `alias` gives it a name.
+ */
+declare function constant(value: number): NumericConstantOperation;
+declare function constant(value: boolean | string | Date): ConstantOperation;
+declare function constant(value: boolean | number | string | Date): ConstantOperation;
+/**
+ * The number of rows in the group, `COUNT(*)`: `f.findAll(null, null, [f.category(), countAll()]).groupBy(f.category())`.
+ * Unlike `count()` of a column it also counts rows where that column is missing.
+ */
+declare function countAll(): CountAllOperation;
+
+/**
+ * A value that depends on a condition, written as in polars:
+ * `when(f.age().gt(30)).then('senior').otherwise('junior')`.
+ */
+
+/** What a branch can be: a column or expression as it is, a plain value as a constant. */
+type Branch = Attribute | RelationalOperationElement | boolean | number | string | Date;
+/**
+ * Something that is true or false for a row, which a `when` can test: a comparison, a null check, a membership
+ * test, `exists`, or `and` / `or` of those. Checked when `when` is called.
+ */
+type Condition = Operation | ExistsOperation | NotExistsOperation;
+type Case = [Condition, RelationalOperationElement];
+/**
+ * `when(condition).then(value)`: a column on its own (missing where the condition does not hold), or continued
+ * with another `when` or closed with `otherwise`.
+ */
+declare class Then extends CaseOperation {
+    private readonly cases;
+    constructor(cases: Case[]);
+    /** Another case, tried when the ones before it do not hold. */
+    when(condition: Condition): When;
+    /** The value when none of the cases hold. */
+    otherwise(branch: Branch): CaseOperation;
 }
-declare class NotExistsOperation extends RelationalOperationElement {
-    readonly node: JoinTreeNodeOperation;
-    constructor(node: JoinTreeNodeOperation);
-    andOp(other: RelationalOperationElement): LogicalOperation;
+declare class When {
+    private readonly condition;
+    private readonly earlier;
+    constructor(condition: Condition, earlier?: Case[]);
+    /** The value where the condition holds. A value is a column, an expression or a plain value. */
+    then(branch: Branch): Then;
 }
+/**
+ * Start a conditional: `when(f.category().eq('Technology')).then('tech').otherwise('other')`.
+ *
+ * Further cases follow with `.when(...).then(...)`; with no `otherwise` the value is missing (NULL). A condition
+ * that is NULL for a row (a comparison with a missing value) is not true, so that row takes the next case.
+ */
+declare function when(condition: Condition): When;
+
+/** Python's `str.title()`: uppercase the first letter of each alphabetic run and lowercase the rest. */
+declare function titleCase(value: string): string;
+
+/**
+ * Join-less alternates for a related class's properties, keyed by dotted property path relative to
+ * that class (e.g. `name`, `branch.city`). The attributes point at flat columns on the owning table.
+ */
+type EmbeddedAttributes = Record<string, Attribute>;
+/** The alternates under `prefix` (e.g. `branch.`), re-keyed relative to it; undefined when there are none. */
+declare function embeddedUnder(embedded: EmbeddedAttributes | undefined, prefix: string): EmbeddedAttributes | undefined;
+
 declare class RelatedFinder {
     private readonly _node;
     constructor(_node: JoinTreeNodeOperation);
@@ -24,4 +83,50 @@ declare class RelatedFinder {
     notExists(): NotExistsOperation;
 }
 
-export { ExistsOperation, JoinTreeNodeOperation, LogicalOperation, NotExistsOperation, RelatedFinder, RelationalOperationElement };
+/**
+ * Runs a query on a Databricks SQL warehouse through the SQL Statement Execution REST API
+ * (`/api/2.0/sql/statements`), which is plain HTTPS and so works from a browser as well as Node.
+ *
+ * A browser cannot call a Databricks workspace directly, as the workspace does not send CORS headers, so
+ * `host` is usually a server of your own that forwards `/api/2.0/sql/…` to the workspace (and may add the
+ * credentials, in which case no `token` is needed here).
+ */
+
+interface DatabricksConfig {
+    /** The workspace URL, or a server that forwards the Statement Execution API to it. No trailing path. */
+    host: string;
+    /** The SQL warehouse that runs the statements. */
+    warehouseId: string;
+    /** Sent as the bearer token. A function is called for every request, so a token can be refreshed. */
+    token?: string | (() => string | Promise<string>);
+    /** The catalog and schema unqualified table names resolve in. */
+    catalog?: string;
+    schema?: string;
+    /** Extra request headers, for a gateway in front of the workspace. */
+    headers?: Record<string, string>;
+    /** `fetch`, if not the global one. */
+    fetch?: typeof fetch;
+    /** How long to wait before first asking again whether a statement has finished (it backs off from there). */
+    pollIntervalMs?: number;
+}
+/** A statement Databricks ran and failed, or the API refused. */
+declare class DatabricksQueryError extends Error {
+    readonly code?: string | undefined;
+    readonly statementId?: string | undefined;
+    constructor(message: string, code?: string | undefined, statementId?: string | undefined);
+}
+declare class DatabricksConnect implements QueryRunner {
+    private readonly config;
+    readonly dialect: "databricks";
+    /** Names of the columns of the last query that returned. */
+    lastColumns: string[];
+    constructor(config: DatabricksConfig);
+    select(businessDate: Date | null, processingDatetime: Date | null, columns: (Attribute | RelationalOperationElement)[], table: QueryTarget, op: RelationalOperationElement, orderBy?: SortOperation[], groupBy?: Attribute[], limit?: number, timeoutMs?: number, businessDateTo?: Date | null, distinct?: boolean, offset?: number, having?: Operation): Promise<Row[]>;
+    /** The rows of a finished statement, following its chunks. */
+    private rows;
+    /** Ask Databricks to stop a statement. Best effort: the query is already given up on. */
+    private cancel;
+    private call;
+}
+
+export { Attribute, CaseOperation, ConstantOperation, CountAllOperation, type DatabricksConfig, DatabricksConnect, DatabricksQueryError, type EmbeddedAttributes, ExistsOperation, JoinTreeNodeOperation, NotExistsOperation, NumericConstantOperation, Operation, QueryRunner, QueryTarget, RelatedFinder, RelationalOperationElement, Row, SortOperation, constant, countAll, embeddedUnder, titleCase, when };

package/dist/index.d.ts

@@ -1,22 +1,81 @@
-export { Attribute } from './datafinder/attribute.js';
+import { Attribute } from './datafinder/attribute.js';
 export { getRelatedFinderClass, registerRelatedFinderClass } from './datafinder/finder-registry.js';
-export { BooleanAttribute, DateAttribute, DateTimeAttribute, DecimalAttribute, DoubleAttribute, FloatAttribute, IntegerAttribute, NumericAttribute, StringAttribute } from './datafinder/typed-attributes.js';
+export { B as BooleanAttribute, D as DateAttribute, a as DateTimeAttribute, b as DecimalAttribute, c as DoubleAttribute, F as FloatAttribute, I as IntegerAttribute, N as NumericAttribute, d as NumericFunctionOperation, S as StringAttribute, e as StringFunctionOperation } from './typed-attributes-CUTf_6Ru.js';
+import { NumericConstantOperation, ConstantOperation, CountAllOperation, Operation, ExistsOperation, NotExistsOperation, RelationalOperationElement, CaseOperation, JoinTreeNodeOperation, SortOperation } from './model/relational.js';
+export { AggregateOperation, AggregateOperator, Aggregates, Alias, Aliasable, Arithmetic, ArithmeticOperand, ArithmeticOperation, ArithmeticOperator, BinaryOperation, BooleanAggregates, BooleanConstantOperation, Column, ColumnWithJoin, Comparable, ComparisonOperation, ComparisonOperator, ConcatOperation, ConcatPart, DATE_ONLY_PATTERN, DataCatalog, DataStore, Database, DateArithmeticOperation, DateConstantOperation, DateDiffOperation, DateExtractOperation, DateOnly, DatePart, DateTimeConstantOperation, DateTruncOperation, DecimalConstantOperation, FloatConstantOperation, ForeignKey, InOperation, IntegerConstantOperation, IsNotNullOperation, IsNullOperation, JoinOperation, LIKE_ESCAPE, LogicalOperation, LogicalOperator, NUMERIC_FUNCTIONS, NoOperation, NotInOperation, ScalarFunction, ScalarFunctionOperation, Schema, SelectOperation, SortDirection, Sortable, StringConstantOperation, StringPredicates, Table, UnaryOperation, WindowFunction, WindowFunctionOperation, WindowSpecification, applyMixins, concat, containsAggregate, containsAggregateOrWindow, escapeLike, operandOf, sample, valueOperand } from './model/relational.js';
 export { selectSqlToString, toSql } from './datafinder/sql-generator.js';
-import { RelationalOperationElement, JoinTreeNodeOperation, LogicalOperation } from './model/relational.js';
-export { AggregateOperation, AggregateOperator, BinaryOperation, BooleanConstantOperation, Column, ColumnWithJoin, ComparisonOperation, ComparisonOperator, ConstantOperation, CountAllOperation, DataCatalog, DataStore, Database, DateArithmeticOperation, DateConstantOperation, DateDiffOperation, DateExtractOperation, DatePart, DateTimeConstantOperation, DecimalConstantOperation, FloatConstantOperation, ForeignKey, IntegerConstantOperation, IsNotNullOperation, IsNullOperation, JoinOperation, LogicalOperator, NoOperation, Operation, ScalarFunction, ScalarFunctionOperation, Schema, SortDirection, SortOperation, StringConstantOperation, Table, UnaryOperation, WindowFunction, WindowFunctionOperation, WindowSpecification } from './model/relational.js';
-export { FinderResult, QueryRunner, QueryTarget, Row, clearRunner, convertInputsAndSelect, getRunner, registerRunner } from './datafinder/runner.js';
+export { D as DATABRICKS, a as DUCKDB, b as DialectName, P as POSTGRES, S as SqlDialect, d as dialectOf } from './dialect-aaG1bDi5.js';
+import { QueryRunner, QueryTarget, Row } from './datafinder/runner.js';
+export { DEFAULT_TIMEOUT_MS, FinderResult, QueryTimeoutError, clearRunner, convertInputsAndSelect, convertInputsAndSelectForDateRange, getRunner, registerRunner } from './datafinder/runner.js';
 export { BiTemporalColumns, BusinessDateAndProcessingTemporalColumns, MilestonedTable, MilestoningColumns, ProcessingTemporalColumns, SingleBusinessDateColumn } from './model/milestoning.js';
 
-declare class ExistsOperation extends RelationalOperationElement {
-    readonly node: JoinTreeNodeOperation;
-    constructor(node: JoinTreeNodeOperation);
-    andOp(other: RelationalOperationElement): LogicalOperation;
+/** Expressions that are not a column of a finder: values to select next to the columns. */
+
+/**
+ * A fixed value as a column: `f.findAll(null, null, [f.name(), constant('EU').alias('Region')])`.
+ * A number is a `NumericConstantOperation`, which takes part in arithmetic: `constant(100).minus(f.price())`.
+ * A `DateOnly` is a date and any other `Date` a timestamp. It is named "Constant" unless `alias` gives it a name.
+ */
+declare function constant(value: number): NumericConstantOperation;
+declare function constant(value: boolean | string | Date): ConstantOperation;
+declare function constant(value: boolean | number | string | Date): ConstantOperation;
+/**
+ * The number of rows in the group, `COUNT(*)`: `f.findAll(null, null, [f.category(), countAll()]).groupBy(f.category())`.
+ * Unlike `count()` of a column it also counts rows where that column is missing.
+ */
+declare function countAll(): CountAllOperation;
+
+/**
+ * A value that depends on a condition, written as in polars:
+ * `when(f.age().gt(30)).then('senior').otherwise('junior')`.
+ */
+
+/** What a branch can be: a column or expression as it is, a plain value as a constant. */
+type Branch = Attribute | RelationalOperationElement | boolean | number | string | Date;
+/**
+ * Something that is true or false for a row, which a `when` can test: a comparison, a null check, a membership
+ * test, `exists`, or `and` / `or` of those. Checked when `when` is called.
+ */
+type Condition = Operation | ExistsOperation | NotExistsOperation;
+type Case = [Condition, RelationalOperationElement];
+/**
+ * `when(condition).then(value)`: a column on its own (missing where the condition does not hold), or continued
+ * with another `when` or closed with `otherwise`.
+ */
+declare class Then extends CaseOperation {
+    private readonly cases;
+    constructor(cases: Case[]);
+    /** Another case, tried when the ones before it do not hold. */
+    when(condition: Condition): When;
+    /** The value when none of the cases hold. */
+    otherwise(branch: Branch): CaseOperation;
 }
-declare class NotExistsOperation extends RelationalOperationElement {
-    readonly node: JoinTreeNodeOperation;
-    constructor(node: JoinTreeNodeOperation);
-    andOp(other: RelationalOperationElement): LogicalOperation;
+declare class When {
+    private readonly condition;
+    private readonly earlier;
+    constructor(condition: Condition, earlier?: Case[]);
+    /** The value where the condition holds. A value is a column, an expression or a plain value. */
+    then(branch: Branch): Then;
 }
+/**
+ * Start a conditional: `when(f.category().eq('Technology')).then('tech').otherwise('other')`.
+ *
+ * Further cases follow with `.when(...).then(...)`; with no `otherwise` the value is missing (NULL). A condition
+ * that is NULL for a row (a comparison with a missing value) is not true, so that row takes the next case.
+ */
+declare function when(condition: Condition): When;
+
+/** Python's `str.title()`: uppercase the first letter of each alphabetic run and lowercase the rest. */
+declare function titleCase(value: string): string;
+
+/**
+ * Join-less alternates for a related class's properties, keyed by dotted property path relative to
+ * that class (e.g. `name`, `branch.city`). The attributes point at flat columns on the owning table.
+ */
+type EmbeddedAttributes = Record<string, Attribute>;
+/** The alternates under `prefix` (e.g. `branch.`), re-keyed relative to it; undefined when there are none. */
+declare function embeddedUnder(embedded: EmbeddedAttributes | undefined, prefix: string): EmbeddedAttributes | undefined;
+
 declare class RelatedFinder {
     private readonly _node;
     constructor(_node: JoinTreeNodeOperation);
@@ -24,4 +83,50 @@ declare class RelatedFinder {
     notExists(): NotExistsOperation;
 }
 
-export { ExistsOperation, JoinTreeNodeOperation, LogicalOperation, NotExistsOperation, RelatedFinder, RelationalOperationElement };
+/**
+ * Runs a query on a Databricks SQL warehouse through the SQL Statement Execution REST API
+ * (`/api/2.0/sql/statements`), which is plain HTTPS and so works from a browser as well as Node.
+ *
+ * A browser cannot call a Databricks workspace directly, as the workspace does not send CORS headers, so
+ * `host` is usually a server of your own that forwards `/api/2.0/sql/…` to the workspace (and may add the
+ * credentials, in which case no `token` is needed here).
+ */
+
+interface DatabricksConfig {
+    /** The workspace URL, or a server that forwards the Statement Execution API to it. No trailing path. */
+    host: string;
+    /** The SQL warehouse that runs the statements. */
+    warehouseId: string;
+    /** Sent as the bearer token. A function is called for every request, so a token can be refreshed. */
+    token?: string | (() => string | Promise<string>);
+    /** The catalog and schema unqualified table names resolve in. */
+    catalog?: string;
+    schema?: string;
+    /** Extra request headers, for a gateway in front of the workspace. */
+    headers?: Record<string, string>;
+    /** `fetch`, if not the global one. */
+    fetch?: typeof fetch;
+    /** How long to wait before first asking again whether a statement has finished (it backs off from there). */
+    pollIntervalMs?: number;
+}
+/** A statement Databricks ran and failed, or the API refused. */
+declare class DatabricksQueryError extends Error {
+    readonly code?: string | undefined;
+    readonly statementId?: string | undefined;
+    constructor(message: string, code?: string | undefined, statementId?: string | undefined);
+}
+declare class DatabricksConnect implements QueryRunner {
+    private readonly config;
+    readonly dialect: "databricks";
+    /** Names of the columns of the last query that returned. */
+    lastColumns: string[];
+    constructor(config: DatabricksConfig);
+    select(businessDate: Date | null, processingDatetime: Date | null, columns: (Attribute | RelationalOperationElement)[], table: QueryTarget, op: RelationalOperationElement, orderBy?: SortOperation[], groupBy?: Attribute[], limit?: number, timeoutMs?: number, businessDateTo?: Date | null, distinct?: boolean, offset?: number, having?: Operation): Promise<Row[]>;
+    /** The rows of a finished statement, following its chunks. */
+    private rows;
+    /** Ask Databricks to stop a statement. Best effort: the query is already given up on. */
+    private cancel;
+    private call;
+}
+
+export { Attribute, CaseOperation, ConstantOperation, CountAllOperation, type DatabricksConfig, DatabricksConnect, DatabricksQueryError, type EmbeddedAttributes, ExistsOperation, JoinTreeNodeOperation, NotExistsOperation, NumericConstantOperation, Operation, QueryRunner, QueryTarget, RelatedFinder, RelationalOperationElement, Row, SortOperation, constant, countAll, embeddedUnder, titleCase, when };