@slonik/sql-tag 40.2.2

package/src/sqlFragmentFactories/createIntervalSqlFragment.ts

@@ -0,0 +1,71 @@
+import { type IntervalSqlToken, type SqlFragment } from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { InvalidInputError } from '@slonik/errors';
+import { z } from 'zod';
+
+const IntervalInput = z
+  .object({
+    days: z.number().optional(),
+    hours: z.number().optional(),
+    minutes: z.number().optional(),
+    months: z.number().optional(),
+    seconds: z.number().optional(),
+    weeks: z.number().optional(),
+    years: z.number().optional(),
+  })
+  .strict();
+
+const intervalFragments = [
+  'years',
+  'months',
+  'weeks',
+  'days',
+  'hours',
+  'minutes',
+  'seconds',
+];
+
+const tokenMap = {
+  minutes: 'mins',
+  seconds: 'secs',
+};
+
+export const createIntervalSqlFragment = (
+  token: IntervalSqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  let intervalInput;
+
+  try {
+    intervalInput = IntervalInput.parse(token.interval);
+  } catch {
+    throw new InvalidInputError(
+      'Interval input must not contain unknown properties.',
+    );
+  }
+
+  const values: number[] = [];
+
+  const intervalTokens: string[] = [];
+
+  for (const intervalFragment of intervalFragments) {
+    const value = intervalInput[intervalFragment];
+
+    if (value !== undefined) {
+      values.push(value);
+
+      const mappedToken = tokenMap[intervalFragment] ?? intervalFragment;
+
+      intervalTokens.push(
+        mappedToken +
+          ' => ' +
+          formatSlonikPlaceholder(greatestParameterPosition + values.length),
+      );
+    }
+  }
+
+  return {
+    sql: 'make_interval(' + intervalTokens.join(', ') + ')',
+    values,
+  };
+};

package/src/sqlFragmentFactories/createJsonSqlFragment.ts

@@ -0,0 +1,66 @@
+import { Logger } from '../Logger';
+import {
+  type JsonBinarySqlToken,
+  type JsonSqlToken,
+  type SqlFragment,
+} from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { isPlainObject } from '../utilities/isPlainObject';
+import { safeStringify } from '../utilities/safeStringify';
+import { InvalidInputError } from '@slonik/errors';
+import { serializeError } from 'serialize-error';
+
+const log = Logger.child({
+  namespace: 'createJsonSqlFragment',
+});
+
+export const createJsonSqlFragment = (
+  token: JsonBinarySqlToken | JsonSqlToken,
+  greatestParameterPosition: number,
+  binary: boolean,
+): SqlFragment => {
+  let value;
+
+  if (token.value === undefined) {
+    throw new InvalidInputError('JSON payload must not be undefined.');
+  } else if (token.value === null) {
+    value = 'null';
+
+    // @todo Deep check Array.
+  } else if (
+    !isPlainObject(token.value) &&
+    !Array.isArray(token.value) &&
+    !['number', 'string', 'boolean'].includes(typeof token.value)
+  ) {
+    throw new InvalidInputError(
+      'JSON payload must be a primitive value or a plain object.',
+    );
+  } else {
+    try {
+      value = safeStringify(token.value);
+    } catch (error) {
+      log.error(
+        {
+          error: serializeError(error),
+        },
+        'payload cannot be stringified',
+      );
+
+      throw new InvalidInputError('JSON payload cannot be stringified.');
+    }
+
+    if (value === undefined) {
+      throw new InvalidInputError(
+        'JSON payload cannot be stringified. The resulting value is undefined.',
+      );
+    }
+  }
+
+  return {
+    sql:
+      formatSlonikPlaceholder(greatestParameterPosition + 1) +
+      '::' +
+      (binary ? 'jsonb' : 'json'),
+    values: [value],
+  };
+};

package/src/sqlFragmentFactories/createListSqlFragment.ts

@@ -0,0 +1,48 @@
+import { createPrimitiveValueExpressions } from '../factories/createPrimitiveValueExpressions';
+import { createSqlTokenSqlFragment } from '../factories/createSqlTokenSqlFragment';
+import {
+  type ListSqlToken,
+  type PrimitiveValueExpression,
+  type SqlFragment,
+} from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { isPrimitiveValueExpression } from '../utilities/isPrimitiveValueExpression';
+import { isSqlToken } from '../utilities/isSqlToken';
+import { InvalidInputError } from '@slonik/errors';
+
+export const createListSqlFragment = (
+  token: ListSqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  const values: PrimitiveValueExpression[] = [];
+  const placeholders: Array<PrimitiveValueExpression | null> = [];
+
+  let placeholderIndex = greatestParameterPosition;
+
+  if (token.members.length === 0) {
+    throw new InvalidInputError('Value list must have at least 1 member.');
+  }
+
+  for (const member of token.members) {
+    if (isSqlToken(member)) {
+      const sqlFragment = createSqlTokenSqlFragment(member, placeholderIndex);
+
+      placeholders.push(sqlFragment.sql);
+      placeholderIndex += sqlFragment.values.length;
+      values.push(...sqlFragment.values);
+    } else if (isPrimitiveValueExpression(member)) {
+      placeholders.push(formatSlonikPlaceholder(++placeholderIndex));
+
+      values.push(member);
+    } else {
+      throw new InvalidInputError(
+        'Invalid list member type. Must be a SQL token or a primitive value expression.',
+      );
+    }
+  }
+
+  return {
+    sql: placeholders.join(token.glue.sql),
+    values: createPrimitiveValueExpressions(values),
+  };
+};

package/src/sqlFragmentFactories/createQuerySqlFragment.ts

@@ -0,0 +1,48 @@
+import { slonikPlaceholderRegexRule } from '../regexRules/slonikPlaceholderRegexRule';
+import { type QuerySqlToken, type SqlFragment } from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { UnexpectedStateError } from '@slonik/errors';
+
+export const createQuerySqlFragment = (
+  token: QuerySqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  let sql = '';
+
+  let leastMatchedParameterPosition = Number.POSITIVE_INFINITY;
+  let greatestMatchedParameterPosition = 0;
+
+  sql += token.sql.replaceAll(slonikPlaceholderRegexRule, (match, g1) => {
+    const parameterPosition = Number.parseInt(g1, 10);
+
+    if (parameterPosition > greatestMatchedParameterPosition) {
+      greatestMatchedParameterPosition = parameterPosition;
+    }
+
+    if (parameterPosition < leastMatchedParameterPosition) {
+      leastMatchedParameterPosition = parameterPosition;
+    }
+
+    return formatSlonikPlaceholder(
+      parameterPosition + greatestParameterPosition,
+    );
+  });
+
+  if (greatestMatchedParameterPosition > token.values.length) {
+    throw new UnexpectedStateError(
+      'The greatest parameter position is greater than the number of parameter values.',
+    );
+  }
+
+  if (
+    leastMatchedParameterPosition !== Number.POSITIVE_INFINITY &&
+    leastMatchedParameterPosition !== 1
+  ) {
+    throw new UnexpectedStateError('Parameter position must start at 1.');
+  }
+
+  return {
+    sql,
+    values: token.values,
+  };
+};

package/src/sqlFragmentFactories/createTimestampSqlFragment.ts

@@ -0,0 +1,22 @@
+import { type SqlFragment, type TimestampSqlToken } from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { InvalidInputError } from '@slonik/errors';
+
+export const createTimestampSqlFragment = (
+  token: TimestampSqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  if (!(token.date instanceof Date)) {
+    throw new InvalidInputError(
+      'Timestamp parameter value must be an instance of Date.',
+    );
+  }
+
+  return {
+    sql:
+      'to_timestamp(' +
+      formatSlonikPlaceholder(greatestParameterPosition + 1) +
+      ')',
+    values: [String(token.date.getTime() / 1_000)],
+  };
+};

package/src/sqlFragmentFactories/createUnnestSqlFragment.ts

@@ -0,0 +1,118 @@
+import {
+  type PrimitiveValueExpression,
+  type SqlFragment,
+  type UnnestSqlToken,
+} from '../types';
+import { countArrayDimensions } from '../utilities/countArrayDimensions';
+import { escapeIdentifier } from '../utilities/escapeIdentifier';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { isPrimitiveValueExpression } from '../utilities/isPrimitiveValueExpression';
+import { stripArrayNotation } from '../utilities/stripArrayNotation';
+import { InvalidInputError } from '@slonik/errors';
+
+export const createUnnestSqlFragment = (
+  token: UnnestSqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  const { columnTypes } = token;
+
+  const values: PrimitiveValueExpression[] = [];
+
+  const unnestBindings: PrimitiveValueExpression[][] = [];
+  const unnestSqlTokens: string[] = [];
+
+  let columnIndex = 0;
+
+  let placeholderIndex = greatestParameterPosition;
+
+  while (columnIndex < columnTypes.length) {
+    const typeMember = columnTypes[columnIndex];
+
+    let columnType = columnTypes[columnIndex];
+    let columnTypeIsIdentifier;
+
+    if (typeof typeMember === 'string') {
+      columnType = typeMember;
+      columnTypeIsIdentifier = false;
+    } else if (Array.isArray(typeMember)) {
+      columnType = typeMember
+        .map((identifierName) => {
+          if (typeof identifierName !== 'string') {
+            throw new InvalidInputError(
+              'sql.unnest column identifier name array member type must be a string (type name identifier) or a SQL token.',
+            );
+          }
+
+          return escapeIdentifier(identifierName);
+        })
+        .join('.');
+      columnTypeIsIdentifier = true;
+    } else {
+      columnType = typeMember.sql;
+      columnTypeIsIdentifier = true;
+    }
+
+    unnestSqlTokens.push(
+      formatSlonikPlaceholder(++placeholderIndex) +
+        '::' +
+        (columnTypeIsIdentifier
+          ? stripArrayNotation(columnType)
+          : escapeIdentifier(stripArrayNotation(columnType))) +
+        '[]'.repeat(countArrayDimensions(columnType) + 1),
+    );
+
+    unnestBindings[columnIndex] = [];
+
+    columnIndex++;
+  }
+
+  let lastTupleSize;
+
+  for (const tupleValues of token.tuples) {
+    if (
+      typeof lastTupleSize === 'number' &&
+      lastTupleSize !== tupleValues.length
+    ) {
+      throw new Error(
+        'Each tuple in a list of tuples must have an equal number of members.',
+      );
+    }
+
+    if (tupleValues.length !== columnTypes.length) {
+      throw new Error('Column types length must match tuple member length.');
+    }
+
+    lastTupleSize = tupleValues.length;
+
+    let tupleColumnIndex = 0;
+
+    for (const tupleValue of tupleValues) {
+      if (
+        !Array.isArray(tupleValue) &&
+        !isPrimitiveValueExpression(tupleValue) &&
+        !Buffer.isBuffer(tupleValue)
+      ) {
+        throw new InvalidInputError(
+          'Invalid unnest tuple member type. Must be a primitive value expression.',
+        );
+      }
+
+      const tupleBindings = unnestBindings[tupleColumnIndex++];
+
+      if (!tupleBindings) {
+        throw new Error('test');
+      }
+
+      tupleBindings.push(tupleValue);
+    }
+  }
+
+  values.push(...unnestBindings);
+
+  const sql = 'unnest(' + unnestSqlTokens.join(', ') + ')';
+
+  return {
+    sql,
+    values,
+  };
+};

package/src/tokens.ts

@@ -0,0 +1,14 @@
+export const ArrayToken = 'SLONIK_TOKEN_ARRAY' as const;
+export const BinaryToken = 'SLONIK_TOKEN_BINARY' as const;
+export const ComparisonPredicateToken =
+  'SLONIK_TOKEN_COMPARISON_PREDICATE' as const;
+export const DateToken = 'SLONIK_TOKEN_DATE' as const;
+export const FragmentToken = 'SLONIK_TOKEN_FRAGMENT' as const;
+export const IdentifierToken = 'SLONIK_TOKEN_IDENTIFIER' as const;
+export const IntervalToken = 'SLONIK_TOKEN_INTERVAL' as const;
+export const JsonBinaryToken = 'SLONIK_TOKEN_JSON_BINARY' as const;
+export const JsonToken = 'SLONIK_TOKEN_JSON' as const;
+export const ListToken = 'SLONIK_TOKEN_LIST' as const;
+export const QueryToken = 'SLONIK_TOKEN_QUERY' as const;
+export const TimestampToken = 'SLONIK_TOKEN_TIMESTAMP' as const;
+export const UnnestToken = 'SLONIK_TOKEN_UNNEST' as const;

package/src/types.ts

@@ -0,0 +1,189 @@
+import type * as tokens from './tokens';
+import { type ZodTypeAny } from 'zod';
+
+export type PrimitiveValueExpression =
+  | Buffer
+  | bigint
+  | boolean
+  | number
+  | string
+  | readonly PrimitiveValueExpression[]
+  | null;
+
+export type SerializableValue =
+  | SerializableValue[]
+  | boolean
+  | number
+  | string
+  | readonly SerializableValue[]
+  | {
+      [key: string]: SerializableValue;
+    }
+  | null
+  | undefined;
+
+export type IntervalInput = {
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  months?: number;
+  seconds?: number;
+  weeks?: number;
+  years?: number;
+};
+
+export type SqlFragment = {
+  readonly sql: string;
+  readonly values: readonly PrimitiveValueExpression[];
+};
+
+export type ValueExpression = PrimitiveValueExpression | SqlFragment | SqlToken;
+
+/**
+ * "string" type covers all type name identifiers – the literal values are added only to assist developer
+ * experience with auto suggestions for commonly used type name identifiers.
+ */
+export type TypeNameIdentifier =
+  | string
+  | 'bool'
+  | 'bytea'
+  | 'float4'
+  | 'float8'
+  | 'int2'
+  | 'int4'
+  | 'int8'
+  | 'json'
+  | 'text'
+  | 'timestamptz'
+  | 'uuid';
+
+export type ArraySqlToken = {
+  readonly memberType: SqlToken | TypeNameIdentifier;
+  readonly type: typeof tokens.ArrayToken;
+  readonly values: readonly PrimitiveValueExpression[];
+};
+
+export type BinarySqlToken = {
+  readonly data: Buffer;
+  readonly type: typeof tokens.BinaryToken;
+};
+
+export type DateSqlToken = {
+  readonly date: Date;
+  readonly type: typeof tokens.DateToken;
+};
+
+export type FragmentSqlToken = {
+  readonly sql: string;
+  readonly type: typeof tokens.FragmentToken;
+  readonly values: readonly PrimitiveValueExpression[];
+};
+
+export type IdentifierSqlToken = {
+  readonly names: readonly string[];
+  readonly type: typeof tokens.IdentifierToken;
+};
+
+export type IntervalSqlToken = {
+  readonly interval: IntervalInput;
+  readonly type: typeof tokens.IntervalToken;
+};
+
+export type ListSqlToken = {
+  readonly glue: SqlFragment;
+  readonly members: readonly ValueExpression[];
+  readonly type: typeof tokens.ListToken;
+};
+
+export type JsonBinarySqlToken = {
+  readonly type: typeof tokens.JsonBinaryToken;
+  readonly value: SerializableValue;
+};
+
+export type JsonSqlToken = {
+  readonly type: typeof tokens.JsonToken;
+  readonly value: SerializableValue;
+};
+
+export type QuerySqlToken<T extends ZodTypeAny = ZodTypeAny> = {
+  readonly parser: T;
+  readonly sql: string;
+  readonly type: typeof tokens.QueryToken;
+  readonly values: readonly PrimitiveValueExpression[];
+};
+
+export type TimestampSqlToken = {
+  readonly date: Date;
+  readonly type: typeof tokens.TimestampToken;
+};
+
+export type UnnestSqlToken = {
+  readonly columnTypes:
+    | Array<[...string[], TypeNameIdentifier]>
+    | Array<SqlFragment | TypeNameIdentifier>;
+  readonly tuples: ReadonlyArray<readonly ValueExpression[]>;
+  readonly type: typeof tokens.UnnestToken;
+};
+
+export type SqlToken =
+  | ArraySqlToken
+  | BinarySqlToken
+  | DateSqlToken
+  | FragmentSqlToken
+  | IdentifierSqlToken
+  | IntervalSqlToken
+  | JsonBinarySqlToken
+  | JsonSqlToken
+  | ListSqlToken
+  | QuerySqlToken
+  | TimestampSqlToken
+  | UnnestSqlToken;
+
+export type SqlTag<Z extends Record<string, ZodTypeAny>> = {
+  array: (
+    values: readonly PrimitiveValueExpression[],
+    memberType: SqlFragment | TypeNameIdentifier,
+  ) => ArraySqlToken;
+  binary: (data: Buffer) => BinarySqlToken;
+  date: (date: Date) => DateSqlToken;
+  fragment: (
+    template: TemplateStringsArray,
+    ...values: ValueExpression[]
+  ) => SqlFragment;
+  identifier: (names: readonly string[]) => IdentifierSqlToken;
+  interval: (interval: IntervalInput) => IntervalSqlToken;
+  join: (
+    members: readonly ValueExpression[],
+    glue: SqlFragment,
+  ) => ListSqlToken;
+  json: (value: SerializableValue) => JsonSqlToken;
+  jsonb: (value: SerializableValue) => JsonBinarySqlToken;
+  literalValue: (value: string) => SqlFragment;
+  timestamp: (date: Date) => TimestampSqlToken;
+  type: <Y extends ZodTypeAny>(
+    parser: Y,
+  ) => (
+    template: TemplateStringsArray,
+    ...values: ValueExpression[]
+  ) => QuerySqlToken<Y>;
+  typeAlias: <K extends keyof Z>(
+    typeAlias: K,
+  ) => (
+    template: TemplateStringsArray,
+    ...values: ValueExpression[]
+  ) => QuerySqlToken<Z[K]>;
+  unnest: (
+    // Value might be ReadonlyArray<ReadonlyArray<PrimitiveValueExpression>>,
+    // or it can be infinitely nested array, e.g.
+    // https://github.com/gajus/slonik/issues/44
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tuples: ReadonlyArray<readonly any[]>,
+    columnTypes:
+      | Array<[...string[], TypeNameIdentifier]>
+      | Array<SqlFragment | TypeNameIdentifier>,
+  ) => UnnestSqlToken;
+  unsafe: (
+    template: TemplateStringsArray,
+    ...values: ValueExpression[]
+  ) => QuerySqlToken;
+};

package/src/utilities/countArrayDimensions.test.ts

@@ -0,0 +1,8 @@
+import { countArrayDimensions } from './countArrayDimensions';
+import test from 'ava';
+
+test('returns the number of array dimensions', (t) => {
+  t.is(countArrayDimensions('foo'), 0);
+  t.is(countArrayDimensions('foo[]'), 1);
+  t.is(countArrayDimensions('foo[][]'), 2);
+});

package/src/utilities/countArrayDimensions.ts

@@ -0,0 +1,12 @@
+export const countArrayDimensions = (identifierName: string): number => {
+  let tail = identifierName.trim();
+  let arrayDimensionCount = 0;
+
+  while (tail.endsWith('[]')) {
+    arrayDimensionCount++;
+
+    tail = tail.trim().slice(0, -2);
+  }
+
+  return arrayDimensionCount;
+};

package/src/utilities/escapeIdentifier.test.ts

@@ -0,0 +1,8 @@
+import { escapeIdentifier } from './escapeIdentifier';
+import test from 'ava';
+
+test('escapes SQL identifiers', (t) => {
+  t.is(escapeIdentifier('foo'), '"foo"');
+  t.is(escapeIdentifier('foo bar'), '"foo bar"');
+  t.is(escapeIdentifier('"foo"'), '"""foo"""');
+});

package/src/utilities/escapeIdentifier.ts

@@ -0,0 +1,8 @@
+const rule = /"/gu;
+
+/**
+ * @see https://github.com/brianc/node-postgres/blob/6c840aabb09f8a2d640800953f6b884b6841384c/lib/client.js#L306-L322
+ */
+export const escapeIdentifier = (identifier: string): string => {
+  return '"' + identifier.replaceAll(rule, '""') + '"';
+};

package/src/utilities/escapeLiteralValue.test.ts

@@ -0,0 +1,9 @@
+import { escapeLiteralValue } from './escapeLiteralValue';
+import test from 'ava';
+
+test('escapes SQL literal value', (t) => {
+  t.is(escapeLiteralValue('foo'), "'foo'");
+  t.is(escapeLiteralValue('foo bar'), "'foo bar'");
+  t.is(escapeLiteralValue('"foo"'), '\'"foo"\'');
+  t.is(escapeLiteralValue('foo\\bar'), "E'foo\\\\bar'");
+});

package/src/utilities/escapeLiteralValue.ts

@@ -0,0 +1,26 @@
+/**
+ * @see https://github.com/brianc/node-postgres/blob/6c840aabb09f8a2d640800953f6b884b6841384c/lib/client.js#L325-L348
+ */
+export const escapeLiteralValue = (subject: string): string => {
+  let hasBackslash = false;
+  let escaped = "'";
+
+  for (const character of subject) {
+    if (character === "'") {
+      escaped += character + character;
+    } else if (character === '\\') {
+      escaped += character + character;
+      hasBackslash = true;
+    } else {
+      escaped += character;
+    }
+  }
+
+  escaped += "'";
+
+  if (hasBackslash === true) {
+    escaped = 'E' + escaped;
+  }
+
+  return escaped;
+};

package/src/utilities/formatSlonikPlaceholder.ts

@@ -0,0 +1,15 @@
+/**
+ * Slonik allows to compose queries using fragments, e.g.
+ * ```ts
+ * sql.fragment`SELECT ${sql.fragment`${1}`}`;
+ * ```
+ * Take a look at the logic in `createFragmentSqlFragment` to see how we detect nested fragments.
+ * When we detect a nested fragment, we need to offset the index of the placeholder.
+ * Historically, we used a placeholder format that was based on the index of the placeholder, e.g. $1, $2, etc.
+ * The problem with that approach was that any mention of $\d inside of a nested fragment was wrongly identified as a placeholder.
+ * To avoid that, we now use a placeholder that is prefixed with $slonik_.
+ * This way, we can safely detect placeholders that are part of a nested fragment.
+ */
+export const formatSlonikPlaceholder = (index: number) => {
+  return '$slonik_' + String(index);
+};

package/src/utilities/hasOwnProperty.ts

@@ -0,0 +1,10 @@
+/**
+ * A stricter type guard.
+ * @see https://tsplay.dev/WK8zGw
+ */
+export const hasOwnProperty = <X extends {}, Y extends PropertyKey>(
+  object: X,
+  property: Y,
+): object is Record<Y, unknown> & X => {
+  return Object.prototype.hasOwnProperty.call(object, property);
+};