@slonik/sql-tag 40.2.2

package/src/factories/createSqlTag.test/unnest.test.ts

@@ -0,0 +1,173 @@
+import { FragmentToken } from '../../tokens';
+import { createSqlTag } from '../createSqlTag';
+import test from 'ava';
+
+const sql = createSqlTag();
+
+test('creates an unnest expression using primitive values (type name identifier)', (t) => {
+  const query = sql.fragment`SELECT * FROM ${sql.unnest(
+    [
+      [1, 2, 3],
+      [4, 5, 6],
+    ],
+    ['int4', 'int4', 'int4'],
+  )}`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT * FROM unnest($slonik_1::"int4"[], $slonik_2::"int4"[], $slonik_3::"int4"[])',
+    type: FragmentToken,
+    values: [
+      [1, 4],
+      [2, 5],
+      [3, 6],
+    ],
+  });
+});
+
+test('creates an unnest expression using primitive values (sql token)', (t) => {
+  const query = sql.fragment`SELECT * FROM ${sql.unnest(
+    [
+      [1, 2, 3],
+      [4, 5, 6],
+    ],
+    [sql.fragment`integer`, sql.fragment`integer`, sql.fragment`integer`],
+  )}`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT * FROM unnest($slonik_1::integer[], $slonik_2::integer[], $slonik_3::integer[])',
+    type: FragmentToken,
+    values: [
+      [1, 4],
+      [2, 5],
+      [3, 6],
+    ],
+  });
+});
+
+test('treats type as sql.identifier', (t) => {
+  const query = sql.fragment`SELECT bar, baz FROM ${sql.unnest(
+    [
+      [1, 3],
+      [2, 4],
+    ],
+    [
+      ['foo', 'int4'],
+      ['foo', 'int4'],
+    ],
+  )} AS foo(bar, baz)`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT bar, baz FROM unnest($slonik_1::"foo"."int4"[], $slonik_2::"foo"."int4"[]) AS foo(bar, baz)',
+    type: FragmentToken,
+    values: [
+      [1, 2],
+      [3, 4],
+    ],
+  });
+});
+
+test('creates an unnest expression using arrays', (t) => {
+  const query = sql.fragment`SELECT * FROM ${sql.unnest(
+    [
+      [1, 2, 3],
+      [4, 5, 6],
+    ],
+    ['int4', 'int4', 'int4'],
+  )}`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT * FROM unnest($slonik_1::"int4"[], $slonik_2::"int4"[], $slonik_3::"int4"[])',
+    type: FragmentToken,
+    values: [
+      [1, 4],
+      [2, 5],
+      [3, 6],
+    ],
+  });
+});
+
+test('creates incremental alias names if no alias names are provided', (t) => {
+  const query = sql.fragment`SELECT * FROM ${sql.unnest(
+    [
+      [1, 2, 3],
+      [4, 5, 6],
+    ],
+    ['int4', 'int4', 'int4'],
+  )}`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT * FROM unnest($slonik_1::"int4"[], $slonik_2::"int4"[], $slonik_3::"int4"[])',
+    type: FragmentToken,
+    values: [
+      [1, 4],
+      [2, 5],
+      [3, 6],
+    ],
+  });
+});
+
+test('recognizes an array of arrays array', (t) => {
+  const query = sql.fragment`SELECT * FROM ${sql.unnest(
+    [[[[1], [2], [3]]]],
+    ['int4[]'],
+  )}`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT * FROM unnest($slonik_1::"int4"[][])',
+    type: FragmentToken,
+    values: [[[[1], [2], [3]]]],
+  });
+});
+
+test('throws if tuple member is not a primitive value expression', (t) => {
+  const error = t.throws(() => {
+    sql.fragment`SELECT * FROM ${sql.unnest(
+      [
+        [
+          // @ts-expect-error Intentional invalid value.
+          () => {},
+          2,
+          3,
+        ],
+        [4, 5],
+      ],
+      ['int4', 'int4', 'int4'],
+    )}`;
+  });
+
+  t.is(
+    error?.message,
+    'Invalid unnest tuple member type. Must be a primitive value expression.',
+  );
+});
+
+test('throws if tuple member length varies in a list of tuples', (t) => {
+  const error = t.throws(() => {
+    sql.fragment`SELECT * FROM ${sql.unnest(
+      [
+        [1, 2, 3],
+        [4, 5],
+      ],
+      ['int4', 'int4', 'int4'],
+    )}`;
+  });
+
+  t.is(
+    error?.message,
+    'Each tuple in a list of tuples must have an equal number of members.',
+  );
+});
+
+test('throws if tuple member length does not match column types length', (t) => {
+  const error = t.throws(() => {
+    sql.fragment`SELECT * FROM ${sql.unnest(
+      [
+        [1, 2, 3],
+        [4, 5, 6],
+      ],
+      ['int4', 'int4'],
+    )}`;
+  });
+
+  t.is(error?.message, 'Column types length must match tuple member length.');
+});

package/src/factories/createSqlTag.ts

@@ -0,0 +1,256 @@
+import { Logger } from '../Logger';
+import {
+  ArrayToken,
+  BinaryToken,
+  DateToken,
+  FragmentToken,
+  IdentifierToken,
+  IntervalToken,
+  JsonBinaryToken,
+  JsonToken,
+  ListToken,
+  QueryToken,
+  TimestampToken,
+  UnnestToken,
+} from '../tokens';
+import {
+  type ArraySqlToken,
+  type BinarySqlToken,
+  type DateSqlToken,
+  type FragmentSqlToken,
+  type IdentifierSqlToken,
+  type IntervalInput,
+  type IntervalSqlToken,
+  type JsonBinarySqlToken,
+  type JsonSqlToken,
+  type ListSqlToken,
+  type PrimitiveValueExpression,
+  type SerializableValue,
+  type SqlFragment,
+  type SqlToken as SqlTokenType,
+  type TimestampSqlToken,
+  type TypeNameIdentifier,
+  type UnnestSqlToken,
+  type ValueExpression,
+} from '../types';
+import { escapeLiteralValue } from '../utilities/escapeLiteralValue';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { isPrimitiveValueExpression } from '../utilities/isPrimitiveValueExpression';
+import { isSqlToken } from '../utilities/isSqlToken';
+import { safeStringify } from '../utilities/safeStringify';
+import { createSqlTokenSqlFragment } from './createSqlTokenSqlFragment';
+import { InvalidInputError } from '@slonik/errors';
+import { z, type ZodTypeAny } from 'zod';
+
+const log = Logger.child({
+  namespace: 'sql',
+});
+
+const createFragment = (
+  parts: readonly string[],
+  values: readonly ValueExpression[],
+) => {
+  let rawSql = '';
+
+  const parameterValues: PrimitiveValueExpression[] = [];
+
+  let index = 0;
+
+  for (const part of parts) {
+    const token = values[index++];
+
+    rawSql += part;
+
+    if (index >= parts.length) {
+      continue;
+    }
+
+    if (token === undefined) {
+      log.debug(
+        {
+          index,
+          parts: JSON.parse(safeStringify(parts)),
+          values: JSON.parse(safeStringify(values)),
+        },
+        'bound values',
+      );
+
+      throw new InvalidInputError(
+        `SQL tag cannot be bound to undefined value at index ${index}.`,
+      );
+    } else if (isPrimitiveValueExpression(token)) {
+      rawSql += formatSlonikPlaceholder(parameterValues.length + 1);
+
+      parameterValues.push(token);
+    } else if (isSqlToken(token)) {
+      const sqlFragment = createSqlTokenSqlFragment(
+        token,
+        parameterValues.length,
+      );
+
+      rawSql += sqlFragment.sql;
+
+      for (const value of sqlFragment.values) {
+        parameterValues.push(value);
+      }
+    } else {
+      log.error(
+        {
+          constructedSql: rawSql,
+          index,
+          offendingToken: JSON.parse(safeStringify(token)),
+        },
+        'unexpected value expression',
+      );
+
+      throw new TypeError('Unexpected value expression.');
+    }
+  }
+
+  return {
+    sql: rawSql,
+    values: parameterValues,
+  };
+};
+
+export const createSqlTag = <
+  K extends PropertyKey,
+  P extends ZodTypeAny,
+  Z extends Record<K, P>,
+>(
+  configuration: {
+    typeAliases?: Z;
+  } = {},
+) => {
+  const typeAliases = configuration.typeAliases;
+
+  return {
+    array: (
+      values: readonly PrimitiveValueExpression[],
+      memberType: SqlTokenType | TypeNameIdentifier,
+    ): ArraySqlToken => {
+      return Object.freeze({
+        memberType,
+        type: ArrayToken,
+        values,
+      });
+    },
+    binary: (data: Buffer): BinarySqlToken => {
+      return Object.freeze({
+        data,
+        type: BinaryToken,
+      });
+    },
+    date: (date: Date): DateSqlToken => {
+      return Object.freeze({
+        date,
+        type: DateToken,
+      });
+    },
+    fragment: (
+      parts: readonly string[],
+      ...args: readonly ValueExpression[]
+    ): FragmentSqlToken => {
+      return Object.freeze({
+        ...createFragment(parts, args),
+        type: FragmentToken,
+      });
+    },
+    identifier: (names: readonly string[]): IdentifierSqlToken => {
+      return Object.freeze({
+        names,
+        type: IdentifierToken,
+      });
+    },
+    interval: (interval: IntervalInput): IntervalSqlToken => {
+      return Object.freeze({
+        interval,
+        type: IntervalToken,
+      });
+    },
+    join: (
+      members: readonly ValueExpression[],
+      glue: SqlFragment,
+    ): ListSqlToken => {
+      return Object.freeze({
+        glue,
+        members,
+        type: ListToken,
+      });
+    },
+    json: (value: SerializableValue): JsonSqlToken => {
+      return Object.freeze({
+        type: JsonToken,
+        value,
+      });
+    },
+    jsonb: (value: SerializableValue): JsonBinarySqlToken => {
+      return Object.freeze({
+        type: JsonBinaryToken,
+        value,
+      });
+    },
+    literalValue: (value: string): SqlFragment => {
+      return Object.freeze({
+        sql: escapeLiteralValue(value),
+        type: FragmentToken,
+        values: [],
+      });
+    },
+    timestamp: (date: Date): TimestampSqlToken => {
+      return Object.freeze({
+        date,
+        type: TimestampToken,
+      });
+    },
+    type: <T extends ZodTypeAny>(parser: T) => {
+      return (
+        parts: readonly string[],
+        ...args: readonly ValueExpression[]
+      ) => {
+        return Object.freeze({
+          ...createFragment(parts, args),
+          parser,
+          type: QueryToken,
+        });
+      };
+    },
+    typeAlias: <Y extends keyof Z>(parserAlias: Y) => {
+      if (!typeAliases?.[parserAlias]) {
+        throw new Error(
+          'Type alias "' + String(parserAlias) + '" does not exist.',
+        );
+      }
+
+      return (
+        parts: readonly string[],
+        ...args: readonly ValueExpression[]
+      ) => {
+        return Object.freeze({
+          ...createFragment(parts, args),
+          parser: typeAliases[parserAlias],
+          type: QueryToken,
+        });
+      };
+    },
+    unnest: (
+      tuples: ReadonlyArray<readonly PrimitiveValueExpression[]>,
+      columnTypes:
+        | Array<[...string[], TypeNameIdentifier]>
+        | Array<SqlFragment | TypeNameIdentifier>,
+    ): UnnestSqlToken => {
+      return Object.freeze({
+        columnTypes,
+        tuples,
+        type: UnnestToken,
+      });
+    },
+    unsafe: (parts: readonly string[], ...args: readonly ValueExpression[]) => {
+      return Object.freeze({
+        ...createFragment(parts, args),
+        parser: z.any(),
+        type: QueryToken,
+      });
+    },
+  };
+};

package/src/factories/createSqlTokenSqlFragment.ts

@@ -0,0 +1,60 @@
+import { createArraySqlFragment } from '../sqlFragmentFactories/createArraySqlFragment';
+import { createBinarySqlFragment } from '../sqlFragmentFactories/createBinarySqlFragment';
+import { createDateSqlFragment } from '../sqlFragmentFactories/createDateSqlFragment';
+import { createFragmentSqlFragment } from '../sqlFragmentFactories/createFragmentSqlFragment';
+import { createIdentifierSqlFragment } from '../sqlFragmentFactories/createIdentifierSqlFragment';
+import { createIntervalSqlFragment } from '../sqlFragmentFactories/createIntervalSqlFragment';
+import { createJsonSqlFragment } from '../sqlFragmentFactories/createJsonSqlFragment';
+import { createListSqlFragment } from '../sqlFragmentFactories/createListSqlFragment';
+import { createQuerySqlFragment } from '../sqlFragmentFactories/createQuerySqlFragment';
+import { createTimestampSqlFragment } from '../sqlFragmentFactories/createTimestampSqlFragment';
+import { createUnnestSqlFragment } from '../sqlFragmentFactories/createUnnestSqlFragment';
+import {
+  ArrayToken,
+  BinaryToken,
+  DateToken,
+  FragmentToken,
+  IdentifierToken,
+  IntervalToken,
+  JsonBinaryToken,
+  JsonToken,
+  ListToken,
+  QueryToken,
+  TimestampToken,
+  UnnestToken,
+} from '../tokens';
+import { type SqlFragment, type SqlToken as SqlTokenType } from '../types';
+import { UnexpectedStateError } from '@slonik/errors';
+
+export const createSqlTokenSqlFragment = (
+  token: SqlTokenType,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  if (token.type === ArrayToken) {
+    return createArraySqlFragment(token, greatestParameterPosition);
+  } else if (token.type === BinaryToken) {
+    return createBinarySqlFragment(token, greatestParameterPosition);
+  } else if (token.type === DateToken) {
+    return createDateSqlFragment(token, greatestParameterPosition);
+  } else if (token.type === FragmentToken) {
+    return createFragmentSqlFragment(token, greatestParameterPosition);
+  } else if (token.type === IdentifierToken) {
+    return createIdentifierSqlFragment(token);
+  } else if (token.type === IntervalToken) {
+    return createIntervalSqlFragment(token, greatestParameterPosition);
+  } else if (token.type === JsonBinaryToken) {
+    return createJsonSqlFragment(token, greatestParameterPosition, true);
+  } else if (token.type === JsonToken) {
+    return createJsonSqlFragment(token, greatestParameterPosition, false);
+  } else if (token.type === ListToken) {
+    return createListSqlFragment(token, greatestParameterPosition);
+  } else if (token.type === QueryToken) {
+    return createQuerySqlFragment(token, greatestParameterPosition);
+  } else if (token.type === TimestampToken) {
+    return createTimestampSqlFragment(token, greatestParameterPosition);
+  } else if (token.type === UnnestToken) {
+    return createUnnestSqlFragment(token, greatestParameterPosition);
+  }
+
+  throw new UnexpectedStateError('Unexpected token type.');
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createSqlTag } from './factories/createSqlTag';
+export { type SqlTag } from './types';

package/src/regexRules/slonikPlaceholderRegexRule.ts

@@ -0,0 +1 @@
+export const slonikPlaceholderRegexRule = /\$slonik_(\d+)/gu;

package/src/sqlFragmentFactories/createArraySqlFragment.ts

@@ -0,0 +1,67 @@
+import { createSqlTokenSqlFragment } from '../factories/createSqlTokenSqlFragment';
+import { type ArraySqlToken, type SqlFragment } from '../types';
+import { escapeIdentifier } from '../utilities/escapeIdentifier';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { isPrimitiveValueExpression } from '../utilities/isPrimitiveValueExpression';
+import { isSqlToken } from '../utilities/isSqlToken';
+import { InvalidInputError, UnexpectedStateError } from '@slonik/errors';
+
+export const createArraySqlFragment = (
+  token: ArraySqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  let placeholderIndex = greatestParameterPosition;
+
+  for (const value of token.values) {
+    if (token.memberType === 'bytea') {
+      if (Buffer.isBuffer(value)) {
+        continue;
+      } else {
+        throw new InvalidInputError(
+          'Invalid array member type. Non-buffer value bound to bytea type.',
+        );
+      }
+    }
+
+    if (!isPrimitiveValueExpression(value)) {
+      throw new InvalidInputError(
+        'Invalid array member type. Must be a primitive value expression.',
+      );
+    }
+  }
+
+  const values = [token.values];
+
+  placeholderIndex++;
+
+  let sql = formatSlonikPlaceholder(placeholderIndex) + '::';
+
+  if (
+    isSqlToken(token.memberType) &&
+    token.memberType.type === 'SLONIK_TOKEN_FRAGMENT'
+  ) {
+    const sqlFragment = createSqlTokenSqlFragment(
+      token.memberType,
+      placeholderIndex,
+    );
+
+    if (sqlFragment.values.length > 0) {
+      throw new UnexpectedStateError(
+        'Type is not expected to have a value binding.',
+      );
+    }
+
+    sql += sqlFragment.sql;
+  } else if (typeof token.memberType === 'string') {
+    sql += escapeIdentifier(token.memberType) + '[]';
+  } else {
+    throw new InvalidInputError(
+      'Unsupported `memberType`. `memberType` must be a string or SqlToken of "SLONIK_TOKEN_FRAGMENT" type.',
+    );
+  }
+
+  return {
+    sql,
+    values,
+  };
+};

package/src/sqlFragmentFactories/createBinarySqlFragment.ts

@@ -0,0 +1,17 @@
+import { type BinarySqlToken, type SqlFragment } from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { InvalidInputError } from '@slonik/errors';
+
+export const createBinarySqlFragment = (
+  token: BinarySqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  if (!Buffer.isBuffer(token.data)) {
+    throw new InvalidInputError('Binary value must be a buffer.');
+  }
+
+  return {
+    sql: formatSlonikPlaceholder(greatestParameterPosition + 1),
+    values: [token.data],
+  };
+};

package/src/sqlFragmentFactories/createDateSqlFragment.ts

@@ -0,0 +1,19 @@
+import { type DateSqlToken, type SqlFragment } from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { InvalidInputError } from '@slonik/errors';
+
+export const createDateSqlFragment = (
+  token: DateSqlToken,
+  greatestParameterPosition: number,
+): SqlFragment => {
+  if (!(token.date instanceof Date)) {
+    throw new InvalidInputError(
+      'Date parameter value must be an instance of Date.',
+    );
+  }
+
+  return {
+    sql: formatSlonikPlaceholder(greatestParameterPosition + 1) + '::date',
+    values: [token.date.toISOString().slice(0, 10)],
+  };
+};

package/src/sqlFragmentFactories/createFragmentSqlFragment.ts

@@ -0,0 +1,48 @@
+import { slonikPlaceholderRegexRule } from '../regexRules/slonikPlaceholderRegexRule';
+import { type FragmentSqlToken, type SqlFragment } from '../types';
+import { formatSlonikPlaceholder } from '../utilities/formatSlonikPlaceholder';
+import { UnexpectedStateError } from '@slonik/errors';
+
+export const createFragmentSqlFragment = (
+  token: FragmentSqlToken,
+  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/createIdentifierSqlFragment.ts

@@ -0,0 +1,24 @@
+import { type IdentifierSqlToken, type SqlFragment } from '../types';
+import { escapeIdentifier } from '../utilities/escapeIdentifier';
+import { InvalidInputError } from '@slonik/errors';
+
+export const createIdentifierSqlFragment = (
+  token: IdentifierSqlToken,
+): SqlFragment => {
+  const sql = token.names
+    .map((identifierName) => {
+      if (typeof identifierName !== 'string') {
+        throw new InvalidInputError(
+          'Identifier name array member type must be a string.',
+        );
+      }
+
+      return escapeIdentifier(identifierName);
+    })
+    .join('.');
+
+  return {
+    sql,
+    values: [],
+  };
+};