safe-string overview

Safe String and it’s building mechanisms allows us to have painless, injection safe SQL string building.

Added in v2.0.0

Table of contents

1. safe-string overview
2. string-builder
   1. buildSerializer
   2. buildSql
   3. castSafe
   4. dsql
   5. isSafeString
3. utils
   1. SafeString (type alias)
   2. SafeStringURI
   3. Serializer (type alias)
   4. SqlStringBuilder (type alias)
   5. SqlStringBuilderOverloadedFn (interface)

string-builder

buildSerializer

Create one serializer.

Signature

export declare const buildSerializer: <T>(args: {
  check: (it: unknown) => it is T;
  serialize: (it: T) => string;
}) => Serializer<T>;

Added in v2.0.0

buildSql

Create a custom version of the sql SafeString builder, using the serializers to serialize values. The types allowed in the string templates will be inferred from the serializers.

Signature

export declare const buildSql: <T extends Serializer<any>[]>(
  serializers: T
) => SqlStringBuilder<T>;

Added in v2.0.0

castSafe

Creates a SafeString from a string.

Useful for embedding other SQL statements in your SQL query, or building helper functions.

Signature

export declare const castSafe: (content: string) => SafeString;

Example

import { castSafe, dsql as sql } from "sql-select-ts";

assert.strictEqual(castSafe(";'abc'").content, ";'abc'");
assert.strictEqual(sql(";'abc'").content, "';\\'abc\\''");

Added in v2.0.0

dsql

Safe-string builder. Works as a function or string template literal.

Signature

export declare const dsql: SqlStringBuilder<never[]>;

Example

import { fromNothing, dsql as sql } from "sql-select-ts";
assert.strictEqual(sql(";'abc'").content, "';\\'abc\\''");
assert.strictEqual(sql(123).content, "123");
assert.strictEqual(sql(null).content, "NULL");
assert.strictEqual(sql`${123} + 456`.content, "123 + 456");
const name = "A";
const names = ["A", "B", "C"];
assert.strictEqual(
  sql`${name} IN (${names})`.content,
  "'A' IN ('A', 'B', 'C')"
);
const q = fromNothing({ it: sql(123) });
assert.strictEqual(sql`${name} IN ${q}`.content, "'A' IN (SELECT 123 AS `it`)");

Added in v2.0.0

isSafeString

Type guard to check if the value is a SafeString.

Signature

export declare const isSafeString: (it: any) => it is SafeString;

Example

import { isSafeString, dsql as sql } from "sql-select-ts";

assert.strictEqual(isSafeString(sql(123)), true);

Added in v2.0.0

utils

SafeString (type alias)

Type used to represent a string that is safe to use in a SQL query.

Signature

export type SafeString = {
  _tag: typeof SafeStringURI;
  content: string;
};

Added in v2.0.0

SafeStringURI

Tag used to discriminate a SafeString object.

Signature

export declare const SafeStringURI: "SafeString";

Added in v2.0.0

Serializer (type alias)

A custom serializer for the SQL string builder.

Signature

export type Serializer<T> = {
  check: (it: unknown) => it is T;
  serialize: (it: T) => string;
};

Added in v2.0.0

SqlStringBuilder (type alias)

A sql builder type based on the serializer types.

Signature

export type SqlStringBuilder<T extends Serializer<any>[]> =
  SqlStringBuilderOverloadedFn<ArgsOfSerializerList<T>>;

Added in v2.0.0

SqlStringBuilderOverloadedFn (interface)

A sql builder generic overloaded function.

Signature

export interface SqlStringBuilderOverloadedFn<T> {
  (it: string | number | null | T): SafeString;
  (
    template: ReadonlyArray<string>,
    ...args: (SqlSupportedTypes | T | readonly (SqlSupportedTypes | T)[])[]
  ): SafeString;
}

Added in v2.0.0