@cipherstash/stack 0.18.0 → 1.0.0-rc.0

package/dist/drizzle/index.d.cts

@@ -1,358 +0,0 @@
-import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { PgTable, PgCustomColumn } from 'drizzle-orm/pg-core';
-import { c as EncryptedTable, f as EncryptedColumn, C as CastAs, M as MatchIndexOpts, T as TokenFilter } from '../types-public-BTxqjmtv.cjs';
-import { a as EncryptionClient } from '../client-Dt98Rugc.cjs';
-import { SQLWrapper, SQL, exists, notExists, isNull, isNotNull, not, arrayContains, arrayContained, arrayOverlaps } from 'drizzle-orm';
-import 'zod';
-import '@cipherstash/protect-ffi';
-import '../errors/index.cjs';
-import '@byteslice/result';
-import '../identity/index.cjs';
-
-/**
- * Extracts the encrypted column keys from a Drizzle table type.
- * Columns created with `encryptedType` are `PgCustomColumn` instances;
- * this picks only those keys and maps them to `EncryptedColumn`.
- */
-type DrizzleEncryptedSchema<T> = {
-    [K in keyof T as T[K] extends PgCustomColumn<any> ? K : never]: EncryptedColumn;
-};
-/**
- * Extracts an encryption schema from a Drizzle table definition.
- * This function identifies columns created with `encryptedType` and
- * builds a corresponding `EncryptedTable` with `encryptedColumn` definitions.
- *
- * @param table - The Drizzle table definition
- * @returns A EncryptedTable that can be used with encryption client initialization
- *
- * @example
- * ```ts
- * const drizzleUsersTable = pgTable('users', {
- *   email: encryptedType('email', { freeTextSearch: true, equality: true }),
- *   age: encryptedType('age', { dataType: 'number', orderAndRange: true }),
- * })
- *
- * const encryptionSchema = extractEncryptionSchema(drizzleUsersTable)
- * const client = await createEncryptionClient({ schemas: [encryptionSchema.build()] })
- * ```
- */
-declare function extractEncryptionSchema<T extends PgTable<any>>(table: T): EncryptedTable<DrizzleEncryptedSchema<T>> & DrizzleEncryptedSchema<T>;
-
-/**
- * Custom error types for better debugging
- */
-declare class EncryptionOperatorError extends Error {
-    readonly context?: {
-        tableName?: string;
-        columnName?: string;
-        operator?: string;
-    } | undefined;
-    constructor(message: string, context?: {
-        tableName?: string;
-        columnName?: string;
-        operator?: string;
-    } | undefined);
-}
-declare class EncryptionConfigError extends EncryptionOperatorError {
-    constructor(message: string, context?: EncryptionOperatorError['context']);
-}
-/**
- * Creates a set of encryption-aware operators that automatically encrypt values
- * for encrypted columns before using them with Drizzle operators.
- *
- * For equality and text search operators (eq, ne, like, ilike, inArray, etc.):
- * Values are encrypted and then passed to regular Drizzle operators, which use
- * PostgreSQL's built-in operators for eql_v2_encrypted types.
- *
- * For order and range operators (gt, gte, lt, lte, between, notBetween):
- * Values are encrypted and then use eql_v2.* functions (eql_v2.gt(), eql_v2.gte(), etc.)
- * which are required for ORE (Order-Revealing Encryption) comparisons.
- *
- * @param encryptionClient - The EncryptionClient instance
- * @returns An object with all Drizzle operators wrapped for encrypted columns
- *
- * @example
- * ```ts
- * // Initialize operators
- * const ops = createEncryptionOperators(encryptionClient)
- *
- * // Equality search - automatically encrypts and uses PostgreSQL operators
- * const results = await db
- *   .select()
- *   .from(usersTable)
- *   .where(await ops.eq(usersTable.email, 'user@example.com'))
- *
- * // Range query - automatically encrypts and uses eql_v2.gte()
- * const olderUsers = await db
- *   .select()
- *   .from(usersTable)
- *   .where(await ops.gte(usersTable.age, 25))
- * ```
- */
-declare function createEncryptionOperators(encryptionClient: EncryptionClient): {
-    /**
-     * Equality operator - encrypts value for encrypted columns.
-     * Requires either `equality` or `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users with a specific email address.
-     * ```ts
-     * const condition = await ops.eq(usersTable.email, 'user@example.com')
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    eq: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * Not equal operator - encrypts value for encrypted columns.
-     * Requires either `equality` or `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users whose email address is not a specific value.
-     * ```ts
-     * const condition = await ops.ne(usersTable.email, 'user@example.com')
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    ne: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * Greater than operator for encrypted columns with ORE index.
-     * Requires `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users older than a specific age.
-     * ```ts
-     * const condition = await ops.gt(usersTable.age, 30)
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    gt: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * Greater than or equal operator for encrypted columns with ORE index.
-     * Requires `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users older than or equal to a specific age.
-     * ```ts
-     * const condition = await ops.gte(usersTable.age, 30)
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    gte: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * Less than operator for encrypted columns with ORE index.
-     * Requires `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users younger than a specific age.
-     * ```ts
-     * const condition = await ops.lt(usersTable.age, 30)
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    lt: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * Less than or equal operator for encrypted columns with ORE index.
-     * Requires `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users younger than or equal to a specific age.
-     * ```ts
-     * const condition = await ops.lte(usersTable.age, 30)
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    lte: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * Between operator for encrypted columns with ORE index.
-     * Requires `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users within a specific age range.
-     * ```ts
-     * const condition = await ops.between(usersTable.age, 20, 30)
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    between: (left: SQLWrapper, min: unknown, max: unknown) => Promise<SQL> | SQL;
-    /**
-     * Not between operator for encrypted columns with ORE index.
-     * Requires `orderAndRange` to be set on {@link EncryptedColumnConfig}.
-     *
-     * @example
-     * Select users outside a specific age range.
-     * ```ts
-     * const condition = await ops.notBetween(usersTable.age, 20, 30)
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    notBetween: (left: SQLWrapper, min: unknown, max: unknown) => Promise<SQL> | SQL;
-    /**
-     * Like operator for encrypted columns with free text search.
-     * Requires `freeTextSearch` to be set on {@link EncryptedColumnConfig}.
-     *
-     * > [!IMPORTANT]
-     * > Case sensitivity on encrypted columns depends on the {@link EncryptedColumnConfig}.
-     * > Ensure that the column is configured for case-insensitive search if needed.
-     *
-     * @example
-     * Select users with email addresses matching a pattern.
-     * ```ts
-     * const condition = await ops.like(usersTable.email, '%@example.com')
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    like: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * ILike operator for encrypted columns with free text search.
-     * Requires `freeTextSearch` to be set on {@link EncryptedColumnConfig}.
-     *
-     * > [!IMPORTANT]
-     * > Case sensitivity on encrypted columns depends on the {@link EncryptedColumnConfig}.
-     * > Ensure that the column is configured for case-insensitive search if needed.
-     *
-     * @example
-     * Select users with email addresses matching a pattern (case-insensitive).
-     * ```ts
-     * const condition = await ops.ilike(usersTable.email, '%@example.com')
-     * const results = await db.select().from(usersTable).where(condition)
-     * ```
-     */
-    ilike: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    notIlike: (left: SQLWrapper, right: unknown) => Promise<SQL> | SQL;
-    /**
-     * JSONB path query first operator for encrypted columns with searchable JSON.
-     * Requires `searchableJson` to be set on {@link EncryptedColumnConfig}.
-     *
-     * Encrypts the JSON path selector and calls `eql_v2.jsonb_path_query_first()`,
-     * casting the parameter to `eql_v2_encrypted`.
-     *
-     * @throws {EncryptionOperatorError} If the column does not have `searchableJson` enabled.
-     */
-    jsonbPathQueryFirst: (left: SQLWrapper, right: unknown) => Promise<SQL>;
-    /**
-     * JSONB get operator for encrypted columns with searchable JSON.
-     * Requires `searchableJson` to be set on {@link EncryptedColumnConfig}.
-     *
-     * Encrypts the JSON path selector and uses the `->` operator,
-     * casting the parameter to `eql_v2_encrypted`.
-     *
-     * @throws {EncryptionOperatorError} If the column does not have `searchableJson` enabled.
-     */
-    jsonbGet: (left: SQLWrapper, right: unknown) => Promise<SQL>;
-    /**
-     * JSONB path exists operator for encrypted columns with searchable JSON.
-     * Requires `searchableJson` to be set on {@link EncryptedColumnConfig}.
-     *
-     * Encrypts the JSON path selector and calls `eql_v2.jsonb_path_exists()`,
-     * casting the parameter to `eql_v2_encrypted`.
-     *
-     * @throws {EncryptionOperatorError} If the column does not have `searchableJson` enabled.
-     */
-    jsonbPathExists: (left: SQLWrapper, right: unknown) => Promise<SQL>;
-    inArray: (left: SQLWrapper, right: unknown[] | SQLWrapper) => Promise<SQL>;
-    notInArray: (left: SQLWrapper, right: unknown[] | SQLWrapper) => Promise<SQL>;
-    asc: (column: SQLWrapper) => SQL;
-    desc: (column: SQLWrapper) => SQL;
-    and: (...conditions: (SQL | SQLWrapper | Promise<SQL> | undefined)[]) => Promise<SQL>;
-    or: (...conditions: (SQL | SQLWrapper | Promise<SQL> | undefined)[]) => Promise<SQL>;
-    exists: typeof exists;
-    notExists: typeof notExists;
-    isNull: typeof isNull;
-    isNotNull: typeof isNotNull;
-    not: typeof not;
-    arrayContains: typeof arrayContains;
-    arrayContained: typeof arrayContained;
-    arrayOverlaps: typeof arrayOverlaps;
-};
-
-/**
- * Configuration for encrypted column indexes and data types
- */
-type EncryptedColumnConfig = {
-    /**
-     * Data type for the column (default: 'string')
-     */
-    dataType?: CastAs;
-    /**
-     * Enable free text search. Can be a boolean for default options, or an object for custom configuration.
-     */
-    freeTextSearch?: boolean | MatchIndexOpts;
-    /**
-     * Enable equality index. Can be a boolean for default options, or an array of token filters.
-     */
-    equality?: boolean | TokenFilter[];
-    /**
-     * Enable order and range index for sorting and range queries.
-     */
-    orderAndRange?: boolean;
-    /**
-     * Enable searchable JSON index for JSONB path queries.
-     * Requires dataType: 'json'.
-     */
-    searchableJson?: boolean;
-};
-/**
- * Creates an encrypted column type for Drizzle ORM with configurable searchable encryption options.
- *
- * When data is encrypted, the actual stored value is an [EQL v2](/docs/reference/eql) encrypted composite type which includes any searchable encryption indexes defined for the column.
- * Importantly, the original data type is not known until it is decrypted. Therefore, this function allows specifying
- * the original data type via the `dataType` option in the configuration.
- * This ensures that when data is decrypted, it can be correctly interpreted as the intended TypeScript type.
- *
- * @typeParam TData - The TypeScript type of the data stored in the column
- * @param name - The column name in the database
- * @param config - Optional configuration for data type and searchable encryption indexes
- * @returns A Drizzle column type that can be used in pgTable definitions
- *
- * ## Searchable Encryption Options
- *
- * - `dataType`: Specifies the original data type of the column (e.g., 'string', 'number', 'json'). Default is 'string'.
- * - `freeTextSearch`: Enables free text search index. Can be a boolean for default options, or an object for custom configuration.
- * - `equality`: Enables equality index. Can be a boolean for default options, or an array of token filters.
- * - `orderAndRange`: Enables order and range index for sorting and range queries.
- * - `searchableJson`: Enables searchable JSON index for JSONB path queries on encrypted JSON columns.
- *
- * See {@link EncryptedColumnConfig}.
- *
- * @example
- * Defining a drizzle table schema for postgres table with encrypted columns.
- *
- * ```typescript
- * import { pgTable, integer, timestamp } from 'drizzle-orm/pg-core'
- * import { encryptedType } from '@cipherstash/stack/drizzle'
- *
- * const users = pgTable('users', {
- *   email: encryptedType('email', {
- *     freeTextSearch: true,
- *     equality: true,
- *     orderAndRange: true,
- *   }),
- *   age: encryptedType('age', {
- *     dataType: 'number',
- *     equality: true,
- *     orderAndRange: true,
- *   }),
- *   profile: encryptedType('profile', {
- *     dataType: 'json',
- *   }),
- * })
- * ```
- */
-declare const encryptedType: <TData>(name: string, config?: EncryptedColumnConfig) => drizzle_orm_pg_core.PgCustomColumnBuilder<{
-    name: string;
-    dataType: "custom";
-    columnType: "PgCustomColumn";
-    data: TData;
-    driverParam: string;
-    enumValues: undefined;
-}>;
-/**
- * Get configuration for an encrypted column by checking if it's an encrypted type
- * and looking up the config by column name
- * @internal
- */
-declare function getEncryptedColumnConfig(columnName: string, column: unknown): (EncryptedColumnConfig & {
-    name: string;
-}) | undefined;
-
-export { CastAs, type EncryptedColumnConfig, EncryptionConfigError, EncryptionOperatorError, MatchIndexOpts, TokenFilter, createEncryptionOperators, encryptedType, extractEncryptionSchema, getEncryptedColumnConfig };