@cipherstash/stack 0.1.0

package/dist/drizzle/index.d.ts

@@ -0,0 +1,350 @@
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { PgTable } from 'drizzle-orm/pg-core';
+import { e as encryptedTable, C as CastAs, M as MatchIndexOpts, T as TokenFilter } from '../types-public-BCj1L4fi.js';
+import { E as EncryptionClient } from '../client-DtGq9dJp.js';
+import { SQLWrapper, SQL, exists, notExists, isNull, isNotNull, not, arrayContains, arrayContained, arrayOverlaps } from 'drizzle-orm';
+import 'zod';
+import 'evlog';
+import '@cipherstash/protect-ffi';
+import '../index-9-Ya3fDK.js';
+import '@byteslice/result';
+
+/**
+ * Extracts an encryption schema from a Drizzle table definition.
+ * This function identifies columns created with `encryptedType` and
+ * builds a corresponding `ProtectTable` with `encryptedColumn` definitions.
+ *
+ * @param table - The Drizzle table definition
+ * @returns A ProtectTable 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): ReturnType<typeof encryptedTable<Record<string, ProtectColumn>>>;
+
+/**
+ * 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 };