adapter-kit is a module in @cipherstash/stack. TypeScript API reference with its signature, parameters, and usage.

D extends V3DomainDefinition

Constructors

Constructor

new EncryptedV3Column&lt;D&gt;(columnName, definition): EncryptedV3Column&lt;D&gt;;

Defined in: eql/v3/columns.ts:474

Methods

getName()

getName(): string;

Defined in: eql/v3/columns.ts:479

getEqlType()

getEqlType(): D["eqlType"];

Defined in: eql/v3/columns.ts:484

The concrete EQL v3 domain name. Metadata only; not emitted by build().

getQueryCapabilities()

getQueryCapabilities(): D["capabilities"];

Defined in: eql/v3/columns.ts:489

The semantic query capabilities this domain exposes. Metadata only.

isQueryable()

isQueryable(): QueryableFlag&lt;D&gt;;

Defined in: eql/v3/columns.ts:494

true when this domain can produce at least one kind of query term.

build()

build(): {
  cast_as:   | "string"
     | "number"
     | "bigint"
     | "boolean"
     | "date"
     | "text"
     | "timestamp"
     | "json";
  indexes: {
     ore?: {
     };
     ope?: {
     };
     unique?: {
        token_filters?: {
           kind: "downcase";
        }[];
     };
     match?: {
        tokenizer?:   | {
           kind: "standard";
         }
           | {
           kind: "ngram";
           token_length: number;
         };
        token_filters?: {
           kind: "downcase";
        }[];
        k?: number;
        m?: number;
        include_original?: boolean;
     };
     ste_vec?: {
        prefix: string;
        array_index_mode?:   | "all"
           | "none"
           | {
           item?: boolean;
           wildcard?: boolean;
           position?: boolean;
         };
        mode?: "standard" | "compat";
     };
  };
};

Defined in: eql/v3/columns.ts:501

Emit the encrypt-config column: cast_as plus capability-derived indexes.

Returns

{
  cast_as:   | "string"
     | "number"
     | "bigint"
     | "boolean"
     | "date"
     | "text"
     | "timestamp"
     | "json";
  indexes: {
     ore?: {
     };
     ope?: {
     };
     unique?: {
        token_filters?: {
           kind: "downcase";
        }[];
     };
     match?: {
        tokenizer?:   | {
           kind: "standard";
         }
           | {
           kind: "ngram";
           token_length: number;
         };
        token_filters?: {
           kind: "downcase";
        }[];
        k?: number;
        m?: number;
        include_original?: boolean;
     };
     ste_vec?: {
        prefix: string;
        array_index_mode?:   | "all"
           | "none"
           | {
           item?: boolean;
           wildcard?: boolean;
           position?: boolean;
         };
        mode?: "standard" | "compat";
     };
  };
}

cast_as

cast_as: 
  | "string"
  | "number"
  | "bigint"
  | "boolean"
  | "date"
  | "text"
  | "timestamp"
  | "json" = castAsEnum;

indexes

indexes: {
  ore?: {
  };
  ope?: {
  };
  unique?: {
     token_filters?: {
        kind: "downcase";
     }[];
  };
  match?: {
     tokenizer?:   | {
        kind: "standard";
      }
        | {
        kind: "ngram";
        token_length: number;
      };
     token_filters?: {
        kind: "downcase";
     }[];
     k?: number;
     m?: number;
     include_original?: boolean;
  };
  ste_vec?: {
     prefix: string;
     array_index_mode?:   | "all"
        | "none"
        | {
        item?: boolean;
        wildcard?: boolean;
        position?: boolean;
      };
     mode?: "standard" | "compat";
  };
} = indexesSchema;

indexes.ore?

optional ore: {
};

indexes.ope?

optional ope: {
};

indexes.unique?

optional unique: {
  token_filters?: {
     kind: "downcase";
  }[];
};

indexes.unique.token_filters?

optional token_filters: {
  kind: "downcase";
}[];

indexes.match?

optional match: {
  tokenizer?:   | {
     kind: "standard";
   }
     | {
     kind: "ngram";
     token_length: number;
   };
  token_filters?: {
     kind: "downcase";
  }[];
  k?: number;
  m?: number;
  include_original?: boolean;
};

indexes.match.tokenizer?

optional tokenizer: 
  | {
  kind: "standard";
}
  | {
  kind: "ngram";
  token_length: number;
} = tokenizerSchema;

indexes.match.token_filters?

optional token_filters: {
  kind: "downcase";
}[];

indexes.match.k?

optional k: number;

indexes.match.m?

optional m: number;

indexes.match.include_original?

optional include_original: boolean;

indexes.ste_vec?

optional ste_vec: {
  prefix: string;
  array_index_mode?:   | "all"
     | "none"
     | {
     item?: boolean;
     wildcard?: boolean;
     position?: boolean;
   };
  mode?: "standard" | "compat";
};

indexes.ste_vec.prefix

prefix: string;

indexes.ste_vec.array_index_mode?

optional array_index_mode: 
  | "all"
  | "none"
  | {
  item?: boolean;
  wildcard?: boolean;
  position?: boolean;
};

indexes.ste_vec.mode?

optional mode: "standard" | "compat";

Type Aliases

AuditConfig

type AuditConfig = {
  metadata?: Record&lt;string, unknown&gt;;
};

Defined in: encryption/operations/base-operation.ts:4

Properties

metadata?

optional metadata: Record&lt;string, unknown&gt;;

Defined in: encryption/operations/base-operation.ts:5

Variables

DATE_LIKE_CASTS

const DATE_LIKE_CASTS: readonly ["date", "timestamp"];

Defined in: eql/v3/columns.ts:36

The cast_as kinds whose decrypted plaintext reconstructs to a JS Date.

SINGLE SOURCE OF TRUTH for the date-like set. Both the type-level PlaintextFromKind and the runtime rowReconstructor (encryption/v3.ts) derive their "reconstructs to Date" decision from this array, so the next Date-backed cast is added in exactly one place — never hand-synced across a type and a runtime guard that could silently drift.

(timestamp reconstructs to Date just like date, but its cast_as tells the FFI not to truncate the time-of-day.)

DOMAIN_REGISTRY

const DOMAIN_REGISTRY: Record&lt;string, V3ColumnFactory&gt;;

Defined in: eql/v3/domain-registry.ts:37

Unqualified Postgres domain_name → the eql/v3/types.ts factory that builds that domain's column.

DERIVED, not hand-listed. Every factory already carries its domain in the constant it passes to the column constructor, so the key is recoverable from the factory itself — and types and this registry cannot drift. Adding a domain to types is enough; forgetting an entry here is no longer possible.

The keys are an external contract (they are the information_schema query parameter in ../../supabase/introspect.ts). Because they are derived from getEqlType(), no test that also derives them can detect a corrupted domain constant — eql-v3-domain-registry.test.ts pins them against a hand-written literal list for exactly that reason.

factory('_probe') runs at module load, so a non-factory value in types would throw here and take the importing modules (../../supabase/introspect.ts, schema-builder.ts, verify.ts) down with it. types is declared satisfies Record<string, V3ColumnFactory> so that mistake is a compile error at its source instead. Do not reintroduce a cast on Object.values below: it would silence exactly the check that keeps this loop total.

logger

const logger: {
  debug: void;
  info: void;
  warn: void;
  error: void;
};

Defined in: utils/logger/index.ts:80

Type Declaration

debug()

debug(...args): void;

Parameters

args

...unknown[]

Returns

void

info()

info(...args): void;

Parameters

args

...unknown[]

Returns

void

warn()

warn(...args): void;

Parameters

args

...unknown[]

Returns

void

error()

error(...args): void;

Parameters

args

...unknown[]

Returns

void

Functions

modelToEncryptedPgComposites()

function modelToEncryptedPgComposites&lt;T&gt;(model): T;

Defined in: encryption/helpers/index.ts:89

Helper function to transform a model's encrypted fields into PostgreSQL composite types

Type Parameters

T

T extends Record<string, unknown>

Parameters

model

T

Returns

T

bulkModelsToEncryptedPgComposites()

function bulkModelsToEncryptedPgComposites&lt;T&gt;(models): T[];

Defined in: encryption/helpers/index.ts:108

Helper function to transform multiple models' encrypted fields into PostgreSQL composite types

Type Parameters

T

T extends Record<string, unknown>

Parameters

models

T[]

Returns

T[]

reconstructDateValue()

function reconstructDateValue(value): unknown;

Defined in: eql/v3/date-reconstruction.ts:12

Rebuild a decrypted plaintext for a date-like model field into a Date. Non-date values and already-constructed Dates pass through untouched.

The Number.isNaN guard is the point of the function, not a formality: an unparseable stored value — a date column written in a non-ISO format, or corrupted — makes new Date(...) an Invalid Date. Returning the raw value instead means the caller sees what is actually stored, rather than an Invalid Date whose later .toISOString() throws far from the column that produced it (#742 review).

Parameters

value

unknown

Returns

unknown

reconstructDatePaths()

function reconstructDatePaths(row, paths): Record&lt;string, unknown&gt;;

Defined in: eql/v3/date-reconstruction.ts:26

Reconstruct date-like values at dotted model paths without mutating the decrypted input row. Missing paths and non-object intermediates are ignored.

Parameters

row

Record<string, unknown>

paths

readonly string[]

Returns

Record<string, unknown>

stripDomainSchema()

function stripDomainSchema(eqlType): string;

Defined in: eql/v3/domain-registry.ts:52

Strip a leading public. schema qualifier from a qualified eqlType.

Parameters

eqlType

string

Returns

string

factoryForDomain()

function factoryForDomain(domainName): V3ColumnFactory | undefined;

Defined in: eql/v3/domain-registry.ts:65

Look up the factory for an unqualified domain name, or undefined.

Object.hasOwn is required, not decorative: without it a domain named constructor / toString / valueOf / __proto__ resolves to an inherited Object.prototype member and violates the "unknown domain = plaintext" rule.

Parameters

domainName

string

Returns

V3ColumnFactory | undefined

parseSelectorSegments()

function parseSelectorSegments(path): string[];

Defined in: eql/v3/selector-path.ts:32

Parse a dot-notation JSONPath into its object-key segments. Rejects, each with a clear message: array-index/wildcard syntax (v1 is object-keys-only), the empty/root path, malformed paths (.., stray/leading/trailing dots, so we never silently query a different path), and prototype-pollution keys. '$.a.b' / ' a.b ' → ['a', 'b'].

Parameters

path

string

Returns

string[]

jsonPathOf()

function jsonPathOf(segments): string;

Defined in: eql/v3/selector-path.ts:72

$-rooted JSONPath for encryptQuery's selector needle.

Parameters

segments

string[]

Returns

string

unsupportedLeafReason()

function unsupportedLeafReason(value, ordering): string | null;

Defined in: eql/v3/selector-path.ts:83

A selector compares a single scalar LEAF. Returns a reason string when value is unsupported — a non-JSON scalar (object/array/Date/bigint), or a boolean under an ordering operator (no ordering term) — else null. Callers raise it as their adapter's operator error with column context, so a bad value is an actionable SDK error rather than a deferred, opaque DB failure.

Parameters

value

unknown

ordering

boolean

Returns

string | null

reconstructSelectorDocument()

function reconstructSelectorDocument(segments, value): Record&lt;string, unknown&gt;;

Defined in: eql/v3/selector-path.ts:120

Nest value under the segments: ['a','b'] → { a: { b: value } }. The storage-needle document whose ste_vec entry at the path supplies the ciphertext-bearing comparison entry.

Parameters

segments

string[]

value

unknown

Returns

Record<string, unknown>

matchNeedleError()

function matchNeedleError(needle, opts): string | undefined;

Defined in: schema/match-defaults.ts:131

Why a needle cannot be answered by this match index, or undefined when it can. Callers throw their own error type with this as the reason.

A needle that tokenizes to NOTHING has an empty bloom filter, and stored_bf @> '{}' is true for every row ("contains nothing, contained by everything"). Such a query is unanswerable rather than merely unmatched, so it must fail loudly instead of silently returning the whole table. Two ways to tokenize to nothing:

the empty needle, under ANY tokenizer;
a needle shorter than the ngram tokenizer's token_length.

The ngram floor counts Unicode CODEPOINTS, because that is what the tokenizer counts. needle.length would count UTF-16 code units and wave through an astral-plane needle: '👍👍' is 4 code units but only 2 codepoints, yields no trigram, and (measured live) matched every row. Graphemes are the wrong unit in the other direction — NFD 'éé' is 4 codepoints but 2 grapheme clusters, and does yield trigrams.

Wired into the v3 adapter surfaces and the core v3 encryptQuery preflight. It lives here, beside the shared match defaults, because v2 builds the same bloom filters and needs the same floor — but v2's like/ilike path remains separate. Do not reuse this for v2 without first measuring what its tokenizer actually receives: v2 needles carry SQL wildcards ('%ada%'), so the floor may have to apply to the unwrapped term rather than to the string the caller passed.

Parameters

needle

unknown

opts

tokenizer?

| { kind: "standard"; } | { kind: "ngram"; token_length: number; } = tokenizerSchema

token_filters?

{ kind: "downcase"; }[] = ...

k?

number = ...

m?

number = ...

include_original?

boolean = ...

Returns

string | undefined

hasBuildColumnKeyMap()

function hasBuildColumnKeyMap&lt;T&gt;(table): table is T & { buildColumnKeyMap: () => Record&lt;string, string&gt; };

Defined in: types.ts:251

The canonical EQL v3 marker: v3 tables expose buildColumnKeyMap(), v2 tables don't. This is the single predicate the codebase uses to decide which wire version a table targets — a second hand-written spelling of the check is how a v2 envelope eventually gets built for a v3 table once the marker drifts, so every site (encryption/index.ts, wasm-inline.ts, dynamodb/helpers.ts) routes through here.

adapter-kit

On this page