pipework 0.251.0 → 0.252.1

package/src/data/migrate/statements.ts

@@ -0,0 +1,312 @@
+/**
+ * One SQL scanner, shared by everything in the migrate pipeline that has to
+ * reason about statement boundaries.
+ *
+ * There were two hand-rolled splitters before this, and they disagreed. The
+ * runner (`parseStatements`) learned string literals and dollar-quoted bodies
+ * in #317 so a plpgsql function body would survive; the safety gate kept a
+ * `sql.split(';')` that then discarded any fragment starting with `--`. Since
+ * a statement and the comment above it land in the *same* fragment, the gate
+ * dropped comment-led statements entirely and reported migrations clean that
+ * dropped tables (#334). Neither splitter knew about block comments or quoted
+ * identifiers.
+ *
+ * The rules, in one place:
+ *
+ * - `--` runs to end of line; block comments nest, per Postgres.
+ * - Comments are removed, replaced by whitespace so they still separate tokens.
+ * - `'…'`, `"…"` and `$tag$…$tag$` are copied verbatim — a `;` or `--` inside
+ *   them is content, not syntax. Backslash escapes apply only in `E'…'`.
+ * - Comment state and quote state are decided in the same pass. That ordering
+ *   is load-bearing: an apostrophe in a comment (`-- the migration's ancestors`)
+ *   must not open a string literal, and a `--` inside a literal must not open
+ *   a comment. Either check running first, alone, gets the other case wrong.
+ * - An unterminated comment or literal runs to end of input; the SQL is invalid
+ *   either way and Postgres is what should say so.
+ */
+
+const IDENT_CHAR = /[A-Za-z0-9_]/
+
+const STATEMENT_BREAKPOINT = '--> statement-breakpoint'
+
+export interface ScanOptions {
+  /**
+   * Honor drizzle's `--> statement-breakpoint` as an explicit statement
+   * separator. The runner needs this (it decides what is sent to Postgres as
+   * one statement); the safety gate does not care.
+   */
+  breakpointSeparator?: boolean
+}
+
+/** Splits SQL into statements, stripping comments. */
+export function scanStatements(sql: string, options: ScanOptions = {}): string[] {
+  const statements: string[] = []
+  let buf = ''
+
+  const flush = (): void => {
+    const stmt = buf.trim()
+    if (stmt.length > 0) statements.push(stmt)
+    buf = ''
+  }
+
+  let i = 0
+  while (i < sql.length) {
+    const c = sql[i]!
+    const next = sql[i + 1]
+
+    // Line comment — runs to the newline, which is left to land as whitespace.
+    if (c === '-' && next === '-') {
+      const nl = sql.indexOf('\n', i)
+      const end = nl === -1 ? sql.length : nl
+      if (options.breakpointSeparator === true && sql.slice(i, end).trim() === STATEMENT_BREAKPOINT) flush()
+      i = end
+      continue
+    }
+
+    // Block comment — Postgres nests these, so track depth.
+    if (c === '/' && next === '*') {
+      i = skipBlockComment(sql, i)
+      buf += ' '
+      continue
+    }
+
+    // Dollar-quoted body — nothing inside is special, only the matching tag ends it.
+    const tag = dollarTagAt(sql, i)
+    if (tag !== null) {
+      const close = sql.indexOf(tag, i + tag.length)
+      const end = close === -1 ? sql.length : close + tag.length
+      buf += sql.slice(i, end)
+      i = end
+      continue
+    }
+
+    // String literal. Backslashes escape only in an E'' string.
+    if (c === "'") {
+      const end = consumeQuoted(sql, i, "'", isEscapeString(sql, i))
+      buf += sql.slice(i, end)
+      i = end
+      continue
+    }
+
+    // Quoted identifier.
+    if (c === '"') {
+      const end = consumeQuoted(sql, i, '"', false)
+      buf += sql.slice(i, end)
+      i = end
+      continue
+    }
+
+    if (c === ';') {
+      flush()
+      i++
+      continue
+    }
+
+    buf += c
+    i++
+  }
+
+  flush()
+  return statements
+}
+
+/**
+ * Removes comments, leaving literals and dollar-quoted bodies intact and
+ * statement separators where they were. For callers that need to test SQL
+ * against a pattern without a comment supplying a false match or hiding a
+ * real one.
+ */
+export function stripComments(sql: string): string {
+  let out = ''
+  let i = 0
+  while (i < sql.length) {
+    const c = sql[i]!
+    const next = sql[i + 1]
+
+    if (c === '-' && next === '-') {
+      const nl = sql.indexOf('\n', i)
+      i = nl === -1 ? sql.length : nl
+      continue
+    }
+    if (c === '/' && next === '*') {
+      i = skipBlockComment(sql, i)
+      out += ' '
+      continue
+    }
+    const tag = dollarTagAt(sql, i)
+    if (tag !== null) {
+      const close = sql.indexOf(tag, i + tag.length)
+      const end = close === -1 ? sql.length : close + tag.length
+      out += sql.slice(i, end)
+      i = end
+      continue
+    }
+    if (c === "'" || c === '"') {
+      const end = consumeQuoted(sql, i, c, c === "'" && isEscapeString(sql, i))
+      out += sql.slice(i, end)
+      i = end
+      continue
+    }
+    out += c
+    i++
+  }
+  return out
+}
+
+/**
+ * Replaces the *contents* of `'…'` string literals with spaces, keeping the
+ * quotes and the overall length.
+ *
+ * A string literal in a migration is data — `INSERT INTO notes VALUES
+ * ('a; DROP TABLE x')` drops nothing. Matching hazard rules against literal
+ * text raises a hazard for inert seed data, and no amount of pattern-tuning
+ * fixes that, because "is this text dangerous" is not answerable from the
+ * text. What makes a literal dangerous is `EXECUTE` running it, which is a
+ * structural fact and gets its own rule.
+ *
+ * Dollar-quoted bodies are deliberately NOT blanked: `DO $$ BEGIN DROP TABLE
+ * x; END $$` is code, and it executes during the migration.
+ */
+export function blankLiterals(sql: string): string {
+  let out = ''
+  let i = 0
+  while (i < sql.length) {
+    const c = sql[i]!
+    const next = sql[i + 1]
+
+    if (c === '-' && next === '-') {
+      const nl = sql.indexOf('\n', i)
+      const end = nl === -1 ? sql.length : nl
+      out += sql.slice(i, end)
+      i = end
+      continue
+    }
+    if (c === '/' && next === '*') {
+      const end = skipBlockComment(sql, i)
+      out += sql.slice(i, end)
+      i = end
+      continue
+    }
+    const tag = dollarTagAt(sql, i)
+    if (tag !== null) {
+      // A dollar-quoted body is code, so it is kept — but the literals inside
+      // that code are still data, so recurse rather than copying it whole.
+      // `DO $$ BEGIN DROP TABLE x; END $$` must keep its DROP TABLE, while
+      // `DO $$ BEGIN EXECUTE 'DROP TABLE x'; END $$` must lose it and be
+      // caught by the EXECUTE rule instead.
+      const close = sql.indexOf(tag, i + tag.length)
+      const end = close === -1 ? sql.length : close + tag.length
+      const inner = sql.slice(i + tag.length, close === -1 ? sql.length : close)
+      out += tag + blankLiterals(inner) + (close === -1 ? '' : tag)
+      i = end
+      continue
+    }
+    if (c === "'") {
+      const end = consumeQuoted(sql, i, "'", isEscapeString(sql, i))
+      const body = sql.slice(i + 1, Math.max(i + 1, end - 1))
+      out += "'" + body.replace(/[^\n]/g, ' ') + (end - i >= 2 ? "'" : '')
+      i = end
+      continue
+    }
+    if (c === '"') {
+      const end = consumeQuoted(sql, i, '"', false)
+      out += sql.slice(i, end)
+      i = end
+      continue
+    }
+    out += c
+    i++
+  }
+  return out
+}
+
+/**
+ * Index of the first character of actual SQL in `sql` — i.e. past any leading
+ * whitespace and comments. Lets a text rewriter skip a leading comment block
+ * without rewriting words inside it.
+ */
+export function codeStartOffset(sql: string): number {
+  let i = 0
+  while (i < sql.length) {
+    const c = sql[i]!
+    if (/\s/.test(c)) {
+      i++
+      continue
+    }
+    if (c === '-' && sql[i + 1] === '-') {
+      const nl = sql.indexOf('\n', i)
+      i = nl === -1 ? sql.length : nl
+      continue
+    }
+    if (c === '/' && sql[i + 1] === '*') {
+      i = skipBlockComment(sql, i)
+      continue
+    }
+    return i
+  }
+  return sql.length
+}
+
+/** `start` indexes the opening `/*`. Returns the index just past the matching close. */
+function skipBlockComment(sql: string, start: number): number {
+  let depth = 0
+  let i = start
+  while (i < sql.length) {
+    if (sql[i] === '/' && sql[i + 1] === '*') {
+      depth++
+      i += 2
+      continue
+    }
+    if (sql[i] === '*' && sql[i + 1] === '/') {
+      depth--
+      i += 2
+      if (depth === 0) return i
+      continue
+    }
+    i++
+  }
+  return sql.length
+}
+
+/**
+ * Returns the dollar-quote tag opening at `i` (`$$`, `$body$`), or null.
+ * Tags may not start with a digit, which is what keeps `$1` positional
+ * parameters from being read as the start of a quoted body.
+ */
+function dollarTagAt(sql: string, i: number): string | null {
+  if (sql[i] !== '$') return null
+  let j = i + 1
+  while (j < sql.length && IDENT_CHAR.test(sql[j]!)) j++
+  if (sql[j] !== '$') return null
+  if (/[0-9]/.test(sql[i + 1] ?? '')) return null
+  return sql.slice(i, j + 1)
+}
+
+/** True when the quote at `i` opens an `E''` escape string. */
+function isEscapeString(sql: string, i: number): boolean {
+  const prev = sql[i - 1]
+  if (prev !== 'e' && prev !== 'E') return false
+  const before = sql[i - 2]
+  return before === undefined || !IDENT_CHAR.test(before)
+}
+
+/** Returns the index just past the closing quote, or end of input if unterminated. */
+function consumeQuoted(sql: string, start: number, quote: string, backslashEscapes: boolean): number {
+  let i = start + 1
+  while (i < sql.length) {
+    const c = sql[i]!
+    if (backslashEscapes && c === '\\') {
+      i += 2
+      continue
+    }
+    if (c === quote) {
+      if (sql[i + 1] === quote) {
+        i += 2
+        continue
+      }
+      return i + 1
+    }
+    i++
+  }
+  return sql.length
+}

package/src/data/query/alias.ts

@@ -0,0 +1,126 @@
+import type { AnyColumn } from './column.js';
+import { Column } from './column.js';
+import { entityKind, is } from './entity.js';
+import type { Relation } from './relations.js';
+import type { View } from './sql/sql.js';
+import { SQL, sql } from './sql/sql.js';
+import { Table } from './table.js';
+import { ViewBaseConfig } from './view-common.js';
+
+export class ColumnAliasProxyHandler<TColumn extends Column> implements ProxyHandler<TColumn> {
+	static readonly [entityKind]: string = 'ColumnAliasProxyHandler';
+
+	constructor(private table: Table | View) {}
+
+	get(columnObj: TColumn, prop: string | symbol): any {
+		if (prop === 'table') {
+			return this.table;
+		}
+
+		return columnObj[prop as keyof TColumn];
+	}
+}
+
+export class TableAliasProxyHandler<T extends Table | View> implements ProxyHandler<T> {
+	static readonly [entityKind]: string = 'TableAliasProxyHandler';
+
+	constructor(private alias: string, private replaceOriginalName: boolean) {}
+
+	get(target: T, prop: string | symbol): any {
+		if (prop === Table.Symbol.IsAlias) {
+			return true;
+		}
+
+		if (prop === Table.Symbol.Name) {
+			return this.alias;
+		}
+
+		if (this.replaceOriginalName && prop === Table.Symbol.OriginalName) {
+			return this.alias;
+		}
+
+		if (prop === ViewBaseConfig) {
+			return {
+				...target[ViewBaseConfig as keyof typeof target],
+				name: this.alias,
+				isAlias: true,
+			};
+		}
+
+		if (prop === Table.Symbol.Columns) {
+			const columns = (target as Table)[Table.Symbol.Columns];
+			if (!columns) {
+				return columns;
+			}
+
+			const proxiedColumns: { [key: string]: any } = {};
+
+			Object.keys(columns).map((key) => {
+				proxiedColumns[key] = new Proxy(
+					columns[key]!,
+					new ColumnAliasProxyHandler(new Proxy(target, this)),
+				);
+			});
+
+			return proxiedColumns;
+		}
+
+		const value = target[prop as keyof typeof target];
+		if (is(value, Column)) {
+			return new Proxy(value as AnyColumn, new ColumnAliasProxyHandler(new Proxy(target, this)));
+		}
+
+		return value;
+	}
+}
+
+export class RelationTableAliasProxyHandler<T extends Relation> implements ProxyHandler<T> {
+	static readonly [entityKind]: string = 'RelationTableAliasProxyHandler';
+
+	constructor(private alias: string) {}
+
+	get(target: T, prop: string | symbol): any {
+		if (prop === 'sourceTable') {
+			return aliasedTable(target.sourceTable, this.alias);
+		}
+
+		return target[prop as keyof typeof target];
+	}
+}
+
+export function aliasedTable<T extends Table | View>(
+	table: T,
+	tableAlias: string,
+): T {
+	return new Proxy(table, new TableAliasProxyHandler(tableAlias, false)) as any;
+}
+
+export function aliasedRelation<T extends Relation>(relation: T, tableAlias: string): T {
+	return new Proxy(relation, new RelationTableAliasProxyHandler(tableAlias));
+}
+
+export function aliasedTableColumn<T extends AnyColumn>(column: T, tableAlias: string): T {
+	return new Proxy(
+		column,
+		new ColumnAliasProxyHandler(new Proxy(column.table, new TableAliasProxyHandler(tableAlias, false))),
+	);
+}
+
+export function mapColumnsInAliasedSQLToAlias(query: SQL.Aliased, alias: string): SQL.Aliased {
+	return new SQL.Aliased(mapColumnsInSQLToAlias(query.sql, alias), query.fieldAlias);
+}
+
+export function mapColumnsInSQLToAlias(query: SQL, alias: string): SQL {
+	return sql.join(query.queryChunks.map((c) => {
+		if (is(c, Column)) {
+			return aliasedTableColumn(c, alias);
+		}
+		if (is(c, SQL)) {
+			return mapColumnsInSQLToAlias(c, alias);
+		}
+		if (is(c, SQL.Aliased)) {
+			return mapColumnsInAliasedSQLToAlias(c, alias);
+		}
+		return c;
+	}));
+}

package/src/data/query/batch.ts

@@ -0,0 +1,8 @@
+import type { Dialect } from './column-builder.js';
+import type { RunnableQuery } from './runnable-query.js';
+
+export type BatchItem<TDialect extends Dialect = Dialect> = RunnableQuery<any, TDialect>;
+
+export type BatchResponse<T extends BatchItem[] | readonly BatchItem[]> = {
+	[K in keyof T]: T[K]['_']['result'];
+};

package/src/data/query/cache/core/cache.ts

@@ -0,0 +1,78 @@
+import { entityKind } from '../../entity.js';
+import type { Table } from '../../index.js';
+import type { CacheConfig } from './types.js';
+
+export abstract class Cache {
+	static readonly [entityKind]: string = 'Cache';
+
+	abstract strategy(): 'explicit' | 'all';
+
+	/**
+	 * Invoked if we should check cache for cached response
+	 * @param sql
+	 * @param tables
+	 */
+	abstract get(
+		key: string,
+		tables: string[],
+		isTag: boolean,
+		isAutoInvalidate?: boolean,
+	): Promise<any[] | undefined>;
+
+	/**
+	 * Invoked if new query should be inserted to cache
+	 * @param sql
+	 * @param tables
+	 */
+	abstract put(
+		hashedQuery: string,
+		response: any,
+		tables: string[],
+		isTag: boolean,
+		config?: CacheConfig,
+	): Promise<void>;
+
+	/**
+	 * Invoked if insert, update, delete was invoked
+	 * @param tables
+	 */
+	abstract onMutate(
+		params: MutationOption,
+	): Promise<void>;
+}
+
+export class NoopCache extends Cache {
+	override strategy() {
+		return 'all' as const;
+	}
+
+	static override readonly [entityKind]: string = 'NoopCache';
+
+	override async get(_key: string): Promise<any[] | undefined> {
+		return undefined;
+	}
+	override async put(
+		_hashedQuery: string,
+		_response: any,
+		_tables: string[],
+		_config?: any,
+	): Promise<void> {
+		// noop
+	}
+	override async onMutate(_params: MutationOption): Promise<void> {
+		// noop
+	}
+}
+
+export type MutationOption = { tags?: string | string[]; tables?: Table<any> | Table<any>[] | string | string[] };
+
+export async function hashQuery(sql: string, params?: any[]) {
+	const dataToHash = `${sql}-${JSON.stringify(params)}`;
+	const encoder = new TextEncoder();
+	const data = encoder.encode(dataToHash);
+	const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+	const hashArray = [...new Uint8Array(hashBuffer)];
+	const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+
+	return hashHex;
+}

package/src/data/query/cache/core/index.ts

@@ -0,0 +1 @@
+export * from './cache.js';

package/src/data/query/cache/core/types.ts

@@ -0,0 +1,29 @@
+export type CacheConfig = {
+	/**
+	 * expire time, in seconds (a positive integer)
+	 */
+	ex?: number;
+	/**
+	 * expire time, in milliseconds (a positive integer).
+	 */
+	px?: number;
+	/**
+	 * Unix time at which the key will expire, in seconds (a positive integer).
+	 */
+	exat?: number;
+	/**
+	 * Unix time at which the key will expire, in milliseconds (a positive integer)
+	 */
+	pxat?: number;
+	/**
+	 * Retain the time to live associated with the key.
+	 */
+	keepTtl?: boolean;
+	/**
+	 * Set an expiration (TTL or time to live) on one or more fields of a given hash key.
+	 * Used for HEXPIRE command
+	 */
+	hexOptions?: 'NX' | 'nx' | 'XX' | 'xx' | 'GT' | 'gt' | 'LT' | 'lt';
+};
+
+export type WithCacheConfig = { enable: boolean; config?: CacheConfig; tag?: string; autoInvalidate?: boolean };