@dalgo/bigquery 0.0.0-stage → 0.3.0

package/dist/sql.js

@@ -0,0 +1,198 @@
+import { DOCUMENT_ID, UnsupportedError } from "@dalgo/core";
+const identifier = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+export function validateIdentifier(value, label) {
+    if (!identifier.test(value))
+        throw new TypeError(`${label} must be a simple BigQuery identifier`);
+}
+/** Google project IDs may contain hyphens, unlike dataset/table/column identifiers. */
+export function validateProjectId(value) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,61}$/u.test(value)) {
+        throw new TypeError("projectId must contain only letters, numbers, and hyphens");
+    }
+}
+function quoteIdentifier(value, label) {
+    validateIdentifier(value, label);
+    return `\`${value}\``;
+}
+export function quoteTable(projectId, table) {
+    validateProjectId(projectId);
+    validateIdentifier(table.datasetId, "datasetId");
+    validateIdentifier(table.tableId, "tableId");
+    return `\`${projectId}.${table.datasetId}.${table.tableId}\``;
+}
+function scalarValue(value, type) {
+    if (value === undefined)
+        throw new TypeError(`${type} parameters cannot be undefined`);
+    if (value === null)
+        return {};
+    switch (type) {
+        case "BOOL":
+            if (typeof value === "boolean")
+                return { value: value ? "true" : "false" };
+            if (value === "true" || value === "false")
+                return { value };
+            throw new TypeError("BOOL parameters require a boolean or BigQuery wire boolean string");
+        case "INT64":
+            if ((typeof value !== "string" && typeof value !== "number") || (typeof value === "number" && !Number.isSafeInteger(value))) {
+                throw new TypeError("INT64 parameters require a decimal string or safe integer");
+            }
+            if (typeof value === "string" && !/^-?(?:0|[1-9]\d*)$/u.test(value)) {
+                throw new TypeError("INT64 parameters require a decimal string or safe integer");
+            }
+            return { value: String(value) };
+        case "FLOAT64":
+            if (typeof value === "number" && Number.isFinite(value))
+                return { value: String(value) };
+            if (typeof value === "string" && value.trim().length > 0 && Number.isFinite(Number(value)))
+                return { value };
+            throw new TypeError("FLOAT64 parameters require a finite number or BigQuery wire float string");
+        case "NUMERIC":
+        case "BIGNUMERIC":
+            if (typeof value !== "string" && typeof value !== "number")
+                throw new TypeError(`${type} parameters require a decimal string or number`);
+            if ((typeof value === "number" && !Number.isFinite(value)) || (typeof value === "string" && !/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/u.test(value))) {
+                throw new TypeError(`${type} parameters require a finite decimal value`);
+            }
+            return { value: String(value) };
+        case "JSON":
+            if (typeof value === "string")
+                return { value };
+            return { value: JSON.stringify(value) };
+        default:
+            if (typeof value !== "string")
+                throw new TypeError(`${type} parameters require a string`);
+            return { value };
+    }
+}
+export function parameter(name, column, value) {
+    return { name, parameterType: { type: column.type }, parameterValue: scalarValue(value, column.type) };
+}
+function arrayParameter(name, column, values) {
+    if (!Array.isArray(values) || values.length === 0)
+        throw new TypeError("in and not-in filters require a non-empty array");
+    if (values.some((value) => value === null))
+        throw new UnsupportedError("BigQuery membership filters containing null");
+    return {
+        name,
+        parameterType: { type: "ARRAY", arrayType: { type: column.type } },
+        parameterValue: { arrayValues: values.map((value) => scalarValue(value, column.type)) },
+    };
+}
+function columnForField(table, field) {
+    if (field === DOCUMENT_ID)
+        return table.keyColumn;
+    const column = table.columns[field];
+    if (column === undefined)
+        throw new UnsupportedError(`BigQuery field not declared in table mapping: ${field}`);
+    return column;
+}
+function columnExpression(column) {
+    return `t.${quoteIdentifier(column.column, "column name")}`;
+}
+function filterSql(filter, table, index) {
+    const column = columnForField(table, String(filter.field));
+    const expr = columnExpression(column);
+    const name = `p${String(index)}`;
+    switch (filter.operator) {
+        case "==": return filter.value === null
+            ? { sql: `${expr} IS NULL` }
+            : { sql: `${expr} = @${name}`, parameter: parameter(name, column, filter.value) };
+        case "!=": return filter.value === null
+            ? { sql: `${expr} IS NOT NULL` }
+            : { sql: `${expr} IS NOT NULL AND ${expr} != @${name}`, parameter: parameter(name, column, filter.value) };
+        case "<": return { sql: `${expr} < @${name}`, parameter: parameter(name, column, filter.value) };
+        case "<=": return { sql: `${expr} <= @${name}`, parameter: parameter(name, column, filter.value) };
+        case ">": return { sql: `${expr} > @${name}`, parameter: parameter(name, column, filter.value) };
+        case ">=": return { sql: `${expr} >= @${name}`, parameter: parameter(name, column, filter.value) };
+        case "in": return { sql: `${expr} IN UNNEST(@${name})`, parameter: arrayParameter(name, column, filter.value) };
+        case "not-in": return { sql: `${expr} IS NOT NULL AND ${expr} NOT IN UNNEST(@${name})`, parameter: arrayParameter(name, column, filter.value) };
+        case "array-contains":
+        case "array-contains-any":
+            throw new UnsupportedError(`BigQuery ${filter.operator} filters on repeated columns`);
+        default:
+            throw new UnsupportedError(`BigQuery query operator: ${String(filter.operator)}`);
+    }
+}
+function orderColumns(orders, table) {
+    const columns = orders.map((order) => columnForField(table, String(order.field)));
+    if (!columns.some((column) => column.column === table.keyColumn.column))
+        return [...columns, table.keyColumn];
+    return columns;
+}
+function requireNonNullableCursorColumns(columns) {
+    for (const column of columns) {
+        if (column.nullable !== false) {
+            throw new UnsupportedError(`BigQuery paginated order requires nullable: false for ${column.column}`);
+        }
+    }
+}
+function orderSql(orders, columns) {
+    return columns.map((column, index) => {
+        const explicit = orders[index];
+        if (explicit !== undefined && explicit.direction !== "asc" && explicit.direction !== "desc") {
+            throw new TypeError("BigQuery order direction must be asc or desc");
+        }
+        return `${columnExpression(column)} ${explicit?.direction === "desc" ? "DESC" : "ASC"}`;
+    }).join(", ");
+}
+function cursorSql(query, columns, parameters) {
+    if (query.startAt !== undefined || query.endAt !== undefined || query.endBefore !== undefined) {
+        throw new UnsupportedError("BigQuery inclusive or end cursors");
+    }
+    if (query.startAfter === undefined)
+        return undefined;
+    if (query.orders.length === 0)
+        throw new UnsupportedError("BigQuery startAfter without an explicit order");
+    if (query.startAfter.values.length !== columns.length) {
+        throw new TypeError("BigQuery cursor value count must include every order field and the key tie-breaker");
+    }
+    if (query.startAfter.values.some((value) => value === null)) {
+        throw new UnsupportedError("BigQuery cursors containing null values");
+    }
+    const terms = [];
+    for (let index = 0; index < columns.length; index += 1) {
+        const column = columns[index];
+        const value = query.startAfter.values[index];
+        if (column === undefined || value === undefined)
+            throw new TypeError("invalid BigQuery cursor");
+        const name = `c${String(index)}`;
+        parameters.push(parameter(name, column, value));
+        const equal = columns.slice(0, index).map((previous, previousIndex) => `${columnExpression(previous)} = @c${String(previousIndex)}`);
+        const direction = query.orders[index]?.direction ?? "asc";
+        if (direction !== "asc" && direction !== "desc")
+            throw new TypeError("BigQuery order direction must be asc or desc");
+        terms.push(`(${[...equal, `${columnExpression(column)} ${direction === "desc" ? "<" : ">"} @${name}`].join(" AND ")})`);
+    }
+    return `(${terms.join(" OR ")})`;
+}
+export function compileBigQueryQuery(projectId, table, query, rowLimit) {
+    if (query.source.kind !== "collection" || query.source.parent !== undefined)
+        throw new UnsupportedError("BigQuery collection-group or nested collection queries");
+    if (!Number.isSafeInteger(rowLimit) || rowLimit < 1)
+        throw new TypeError("row limit must be a positive safe integer");
+    const parameters = [];
+    const clauses = query.filters.map((filter, index) => {
+        const compiled = filterSql(filter, table, index);
+        if (compiled.parameter !== undefined)
+            parameters.push(compiled.parameter);
+        return compiled.sql;
+    });
+    const cursorColumns = orderColumns(query.orders, table);
+    if (query.orders.length > 0) {
+        requireNonNullableCursorColumns(cursorColumns);
+    }
+    const cursor = cursorSql(query, cursorColumns, parameters);
+    if (cursor !== undefined)
+        clauses.push(cursor);
+    const selected = [
+        `${columnExpression(table.keyColumn)} AS \`__dalgo_key\``,
+        ...Object.entries(table.columns).map(([field, column]) => `${columnExpression(column)} AS ${quoteIdentifier(field, "field name")}`),
+    ];
+    const where = clauses.length === 0 ? "" : ` WHERE ${clauses.join(" AND ")}`;
+    const ordered = query.orders.length === 0 ? "" : ` ORDER BY ${orderSql(query.orders, cursorColumns)}`;
+    return {
+        sql: `SELECT ${selected.join(", ")} FROM ${quoteTable(projectId, table)} AS t${where}${ordered} LIMIT ${String(rowLimit)}`,
+        parameters,
+        cursorColumns,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+/** Supported scalar parameter types for mapped BigQuery columns. */
+export type BigQueryScalarType = "STRING" | "INT64" | "FLOAT64" | "BOOL" | "NUMERIC" | "BIGNUMERIC" | "DATE" | "DATETIME" | "TIME" | "TIMESTAMP" | "JSON";
+export interface BigQueryColumn {
+    /** BigQuery column name. Nested/repeated columns are deliberately unsupported. */
+    readonly column: string;
+    readonly type: BigQueryScalarType;
+    /** Required as false for an ordered field that participates in DALgo pagination. */
+    readonly nullable?: boolean;
+}
+/**
+ * The bounded record projection that a DALgo collection represents.
+ * All application fields that this adapter reads or writes must be declared in
+ * `columns`; unrelated warehouse columns remain outside DALgo's model.
+ */
+export interface BigQueryTable {
+    readonly datasetId: string;
+    readonly tableId: string;
+    readonly keyColumn: BigQueryColumn;
+    readonly columns: Readonly<Record<string, BigQueryColumn>>;
+}
+export type AccessTokenProvider = () => string | Promise<string>;
+export type BigQueryFetch = typeof globalThis.fetch;
+export interface BigQueryDatabaseOptions {
+    /** Google Cloud project that owns query jobs. */
+    readonly projectId: string;
+    /** Maps each DALgo collection name to one bounded BigQuery table projection. */
+    readonly tables: Readonly<Record<string, BigQueryTable>>;
+    /** Returns a short-lived OAuth 2.0 access token for every request. */
+    readonly accessToken: AccessTokenProvider;
+    readonly location?: string;
+    /** Caps query cost; omitted only when the caller explicitly accepts project defaults. */
+    readonly maximumBytesBilled?: bigint | number | string;
+    /** Maximum DALgo records returned by one query; defaults to 1000. */
+    readonly maxRows?: number;
+    /** Maximum rows requested from one BigQuery results response; defaults to 500. */
+    readonly pageSize?: number;
+    /** End-to-end request and polling deadline; defaults to 30 seconds. */
+    readonly timeoutMs?: number;
+    /** Initial synchronous wait supplied to jobs.query; defaults to 1000 milliseconds. */
+    readonly initialWaitMs?: number;
+    readonly fetch?: BigQueryFetch;
+}
+export interface BigQueryQueryMetadata {
+    readonly jobId?: string;
+    readonly totalBytesProcessed?: string;
+    readonly totalBytesBilled?: string;
+    readonly cacheHit?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,OAAO,GACP,SAAS,GACT,MAAM,GACN,SAAS,GACT,YAAY,GACZ,MAAM,GACN,UAAU,GACV,MAAM,GACN,WAAW,GACX,MAAM,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AACjE,MAAM,MAAM,aAAa,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAEpD,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACvD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@dalgo/bigquery",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "BigQuery REST API adapter for DALgo TypeScript",
+  "type": "module",
+  "packageManager": "pnpm@11.20.0",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./analytical": {
+      "types": "./dist/analytical.d.ts",
+      "import": "./dist/analytical.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "eslint . && vitest run && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dal-go/dalgo-http-adapters.git",
+    "directory": "packages/bigquery"
+  },
+  "bugs": {
+    "url": "https://github.com/dal-go/dalgo-http-adapters/issues"
+  },
+  "homepage": "https://github.com/dal-go/dalgo-http-adapters/tree/main/packages/bigquery#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@dalgo/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@dalgo/core": "0.1.0",
+    "@eslint/js": "10.0.1",
+    "eslint": "10.11.0",
+    "fake-indexeddb": "6.2.5",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "10d0d6575c38338350feb7a9284530561f5b139e"
+}