@cipherstash/stack 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @cipherstash/stack
 
+## 0.3.0
+
+### Minor Changes
+
+- afe0a55: Improved encrypt model return types to account for Encrypted values.
+
+## 0.2.0
+
+### Minor Changes
+
+- 68c8199: Improved typing for model interfaces and full bun support.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -139,29 +139,27 @@ const decrypted = await client.decrypt(encrypted.data)
 
 Encrypt or decrypt an entire object. Only fields matching your schema are encrypted; other fields pass through unchanged.
 
+The return type is **schema-aware**: fields matching the table schema are typed as `Encrypted`, while other fields retain their original types. For best results, let TypeScript infer the type parameters from the arguments:
+
 ```typescript
+type User = { id: string; email: string; createdAt: Date }
+
 const user = {
   id: "user_123",
   email: "alice@example.com",  // defined in schema -> encrypted
   createdAt: new Date(),       // not in schema -> unchanged
 }
 
-// Encrypt a model
+// Let TypeScript infer the return type from the schema
 const encryptedResult = await client.encryptModel(user, users)
+// encryptedResult.data.email    -> Encrypted
+// encryptedResult.data.id       -> string
+// encryptedResult.data.createdAt -> Date
 
 // Decrypt a model
 const decryptedResult = await client.decryptModel(encryptedResult.data)
 ```
 
-Type-safe generics are supported:
-
-```typescript
-type User = { id: string; email: string; createdAt: Date }
-
-const result = await client.encryptModel<User>(user, users)
-const back = await client.decryptModel<User>(result.data)
-```
-
 ### Bulk Operations
 
 All bulk methods make a single call to ZeroKMS regardless of the number of records, while still using a unique key per value.
@@ -592,11 +590,11 @@ function Encryption(config: EncryptionClientConfig): Promise<EncryptionClient>
 | `decrypt` | `(encryptedData)` | `DecryptOperation` (thenable) |
 | `encryptQuery` | `(plaintext, { column, table, queryType?, returnType? })` | `EncryptQueryOperation` (thenable) |
 | `encryptQuery` | `(terms: ScalarQueryTerm[])` | `BatchEncryptQueryOperation` (thenable) |
-| `encryptModel` | `(model, table)` | `EncryptModelOperation<T>` (thenable) |
+| `encryptModel` | `(model, table)` | `EncryptModelOperation<EncryptedFromSchema<T, S>>` (thenable) |
 | `decryptModel` | `(encryptedModel)` | `DecryptModelOperation<T>` (thenable) |
 | `bulkEncrypt` | `(plaintexts, { column, table })` | `BulkEncryptOperation` (thenable) |
 | `bulkDecrypt` | `(encryptedPayloads)` | `BulkDecryptOperation` (thenable) |
-| `bulkEncryptModels` | `(models, table)` | `BulkEncryptModelsOperation<T>` (thenable) |
+| `bulkEncryptModels` | `(models, table)` | `BulkEncryptModelsOperation<EncryptedFromSchema<T, S>>` (thenable) |
 | `bulkDecryptModels` | `(encryptedModels)` | `BulkDecryptModelsOperation<T>` (thenable) |
 
 All operations are thenable (awaitable) and support `.withLockContext(lockContext)` for identity-aware encryption.
@@ -629,7 +627,7 @@ await secrets.delete(name)
 import { encryptedTable, encryptedColumn, csValue } from "@cipherstash/stack/schema"
 
 encryptedTable(tableName, columns)
-encryptedColumn(columnName)        // returns ProtectColumn
+encryptedColumn(columnName)        // returns EncryptedColumn
 csValue(valueName)                 // returns ProtectValue (for nested values)
 ```
 
@@ -663,7 +661,6 @@ All method signatures on the encryption client (`encrypt`, `decrypt`, `encryptMo
 
 - **Node.js** >= 18
 - The package includes a native FFI module (`@cipherstash/protect-ffi`) written in Rust and embedded via [Neon](https://github.com/neon-bindings/neon). You must opt out of bundling this package in tools like Webpack, esbuild, or Next.js (`serverExternalPackages`).
-- [Bun](https://bun.sh/) is not currently supported due to incomplete Node-API compatibility.
 
 ## License
 

package/dist/bin/stash.js

@@ -1561,7 +1561,7 @@ var encryptConfigSchema = z2.object({
   v: z2.number(),
   tables: tablesSchema
 });
-var ProtectValue = class {
+var EncryptedField = class {
   valueName;
   castAsValue;
   constructor(valueName) {
@@ -1569,20 +1569,20 @@ var ProtectValue = class {
     this.castAsValue = "string";
   }
   /**
-   * Set or override the plaintext data type for this value.
+   * Set or override the plaintext data type for this field.
    *
    * By default all values are treated as `'string'`. Use this method to specify
    * a different type so the encryption layer knows how to encode the plaintext
    * before encrypting.
    *
    * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'bigint'`, or `'json'`.
-   * @returns This `ProtectValue` instance for method chaining.
+   * @returns This `EncryptedField` instance for method chaining.
    *
    * @example
    * ```typescript
-   * import { encryptedValue } from "@cipherstash/stack/schema"
+   * import { encryptedField } from "@cipherstash/stack/schema"
    *
-   * const age = encryptedValue("age").dataType("number")
+   * const age = encryptedField("age").dataType("number")
    * ```
    */
   dataType(castAs) {
@@ -1599,7 +1599,7 @@ var ProtectValue = class {
     return this.valueName;
   }
 };
-var ProtectColumn = class {
+var EncryptedColumn = class {
   columnName;
   castAsValue;
   indexesValue = {};
@@ -1615,7 +1615,7 @@ var ProtectColumn = class {
    * before encrypting.
    *
    * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'bigint'`, or `'json'`.
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -1634,7 +1634,7 @@ var ProtectColumn = class {
    * ORE allows sorting, comparison, and range queries on encrypted data.
    * Use with `encryptQuery` and `queryType: 'orderAndRange'`.
    *
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -1657,7 +1657,7 @@ var ProtectColumn = class {
    *
    * @param tokenFilters - Optional array of token filters (e.g. `[{ kind: 'downcase' }]`).
    *   When omitted, no token filters are applied.
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -1682,7 +1682,7 @@ var ProtectColumn = class {
    *
    * @param opts - Optional match index configuration. Defaults to 3-character ngram
    *   tokenization with a downcase filter, `k=6`, `m=2048`, and `include_original=true`.
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -1727,7 +1727,7 @@ var ProtectColumn = class {
    * the plaintext type: strings become selector queries, objects/arrays become
    * containment queries.
    *
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -1753,7 +1753,7 @@ var ProtectColumn = class {
     return this.columnName;
   }
 };
-var ProtectTable = class {
+var EncryptedTable = class {
   constructor(tableName, columnBuilders) {
     this.tableName = tableName;
     this.columnBuilders = columnBuilders;
@@ -1780,7 +1780,7 @@ var ProtectTable = class {
   build() {
     const builtColumns = {};
     const processColumn = (builder, colName) => {
-      if (builder instanceof ProtectColumn) {
+      if (builder instanceof EncryptedColumn) {
         const builtColumn = builder.build();
         if (builtColumn.cast_as === "json" && builtColumn.indexes.ste_vec?.prefix === "enabled") {
           builtColumns[colName] = {
@@ -1797,7 +1797,7 @@ var ProtectTable = class {
         }
       } else {
         for (const [key, value] of Object.entries(builder)) {
-          if (value instanceof ProtectValue) {
+          if (value instanceof EncryptedField) {
             builtColumns[value.getName()] = value.build();
           } else {
             processColumn(value, key);
@@ -1815,7 +1815,10 @@ var ProtectTable = class {
   }
 };
 function encryptedTable(tableName, columns) {
-  const tableBuilder = new ProtectTable(tableName, columns);
+  const tableBuilder = new EncryptedTable(
+    tableName,
+    columns
+  );
   for (const [colName, colBuilder] of Object.entries(columns)) {
     ;
     tableBuilder[colName] = colBuilder;
@@ -1823,7 +1826,7 @@ function encryptedTable(tableName, columns) {
   return tableBuilder;
 }
 function encryptedColumn(columnName) {
-  return new ProtectColumn(columnName);
+  return new EncryptedColumn(columnName);
 }
 function buildEncryptConfig(...protectTables) {
   const config3 = {
@@ -1917,7 +1920,7 @@ function initStackLogger(config3) {
   const rates = samplingFromEnv();
   initLogger({
     env: { service: "@cipherstash/stack" },
-    enabled: config3?.enabled ?? true,
+    enabled: config3?.enabled ?? !!rates,
     pretty: config3?.pretty,
     ...rates && { sampling: { rates } },
     ...config3?.drain && { drain: config3.drain }
@@ -1930,7 +1933,11 @@ function safeMessage(args) {
 var logger = {
   debug(...args) {
     const log = createRequestLogger();
-    log.set({ level: "debug", source: "@cipherstash/stack", message: safeMessage(args) });
+    log.set({
+      level: "debug",
+      source: "@cipherstash/stack",
+      message: safeMessage(args)
+    });
     log.emit();
   },
   info(...args) {
@@ -1951,16 +1958,16 @@ var logger = {
   }
 };
 
-// src/encryption/ffi/index.ts
+// src/encryption/index.ts
 import { withResult as withResult11 } from "@byteslice/result";
 import { newClient } from "@cipherstash/protect-ffi";
 
-// src/encryption/ffi/helpers/type-guards.ts
+// src/encryption/helpers/type-guards.ts
 function isScalarQueryTermArray(value) {
   return Array.isArray(value) && value.length > 0 && typeof value[0] === "object" && value[0] !== null && "column" in value[0] && "table" in value[0];
 }
 
-// src/encryption/ffi/helpers/error-code.ts
+// src/encryption/helpers/error-code.ts
 import {
   ProtectError as FfiProtectError
 } from "@cipherstash/protect-ffi";
@@ -1968,7 +1975,7 @@ function getErrorCode(error) {
   return error instanceof FfiProtectError ? error.code : void 0;
 }
 
-// src/encryption/ffi/operations/batch-encrypt-query.ts
+// src/encryption/operations/batch-encrypt-query.ts
 import { withResult } from "@byteslice/result";
 import {
   encryptQueryBulk as ffiEncryptQueryBulk
@@ -1988,7 +1995,7 @@ var queryTypeToQueryOp = {
   steVecTerm: "ste_vec_term"
 };
 
-// src/encryption/ffi/helpers/infer-index-type.ts
+// src/encryption/helpers/infer-index-type.ts
 function inferIndexType(column) {
   const config3 = column.build();
   const indexes = config3.indexes;
@@ -2048,7 +2055,7 @@ function resolveIndexType(column, queryType, plaintext) {
   return { indexType };
 }
 
-// src/encryption/ffi/helpers/validation.ts
+// src/encryption/helpers/validation.ts
 function validateNumericValue(value) {
   if (typeof value === "number" && Number.isNaN(value)) {
     return {
@@ -2084,7 +2091,7 @@ function assertValueIndexCompatibility(value, indexType, columnName) {
   }
 }
 
-// src/encryption/ffi/operations/base-operation.ts
+// src/encryption/operations/base-operation.ts
 var EncryptionOperation = class {
   auditMetadata;
   /**
@@ -2112,7 +2119,7 @@ var EncryptionOperation = class {
   }
 };
 
-// src/encryption/ffi/operations/batch-encrypt-query.ts
+// src/encryption/operations/batch-encrypt-query.ts
 function filterNullTerms(terms) {
   const nullIndices = /* @__PURE__ */ new Set();
   const nonNullTerms = [];
@@ -2267,7 +2274,7 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/bulk-decrypt.ts
+// src/encryption/operations/bulk-decrypt.ts
 import { withResult as withResult2 } from "@byteslice/result";
 import {
   decryptBulkFallible
@@ -2420,10 +2427,10 @@ var BulkDecryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/bulk-decrypt-models.ts
+// src/encryption/operations/bulk-decrypt-models.ts
 import { withResult as withResult3 } from "@byteslice/result";
 
-// src/encryption/ffi/model-helpers.ts
+// src/encryption/helpers/model-helpers.ts
 import {
   decryptBulk,
   encryptBulk
@@ -2941,7 +2948,7 @@ async function bulkEncryptModelsWithLockContext(models, table, client, lockConte
   });
 }
 
-// src/encryption/ffi/operations/bulk-decrypt-models.ts
+// src/encryption/operations/bulk-decrypt-models.ts
 var BulkDecryptModelsOperation = class extends EncryptionOperation {
   client;
   models;
@@ -3038,7 +3045,7 @@ var BulkDecryptModelsOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/bulk-encrypt.ts
+// src/encryption/operations/bulk-encrypt.ts
 import { withResult as withResult4 } from "@byteslice/result";
 import { encryptBulk as encryptBulk2 } from "@cipherstash/protect-ffi";
 var createEncryptPayloads = (plaintexts, column, table, lockContext) => {
@@ -3203,7 +3210,7 @@ var BulkEncryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/bulk-encrypt-models.ts
+// src/encryption/operations/bulk-encrypt-models.ts
 import { withResult as withResult5 } from "@byteslice/result";
 var BulkEncryptModelsOperation = class extends EncryptionOperation {
   client;
@@ -3312,7 +3319,7 @@ var BulkEncryptModelsOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/decrypt.ts
+// src/encryption/operations/decrypt.ts
 import { withResult as withResult6 } from "@byteslice/result";
 import {
   decrypt as ffiDecrypt
@@ -3421,7 +3428,7 @@ var DecryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/decrypt-model.ts
+// src/encryption/operations/decrypt-model.ts
 import { withResult as withResult7 } from "@byteslice/result";
 var DecryptModelOperation = class extends EncryptionOperation {
   client;
@@ -3517,7 +3524,7 @@ var DecryptModelOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt.ts
+// src/encryption/operations/encrypt.ts
 import { withResult as withResult8 } from "@byteslice/result";
 import {
   encrypt as ffiEncrypt
@@ -3645,7 +3652,7 @@ var EncryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt-model.ts
+// src/encryption/operations/encrypt-model.ts
 import { withResult as withResult9 } from "@byteslice/result";
 var EncryptModelOperation = class extends EncryptionOperation {
   client;
@@ -3752,7 +3759,7 @@ var EncryptModelOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt-query.ts
+// src/encryption/operations/encrypt-query.ts
 import { withResult as withResult10 } from "@byteslice/result";
 import {
   encryptQuery as ffiEncryptQuery
@@ -3904,9 +3911,9 @@ var EncryptQueryOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/index.ts
+// src/encryption/index.ts
 var noClientError = () => new Error(
-  "The EQL client has not been initialized. Please call init() before using the client."
+  "The Encryption client has not been initialized. Please call init() before using the client."
 );
 var EncryptionClient = class {
   client;
@@ -3929,7 +3936,7 @@ var EncryptionClient = class {
           config3.encryptConfig
         );
         logger.debug(
-          "Initializing the Protect.js client with the following encrypt config:",
+          "Initializing the Encryption client with the following config:",
           {
             encryptConfig: validated
           }
@@ -3937,15 +3944,15 @@ var EncryptionClient = class {
         this.client = await newClient({
           encryptConfig: validated,
           clientOpts: {
-            workspaceCrn: config3.workspaceCrn,
-            accessKey: config3.accessKey,
-            clientId: config3.clientId,
-            clientKey: config3.clientKey,
+            workspaceCrn: config3.workspaceCrn ?? process.env.CS_WORKSPACE_CRN,
+            accessKey: config3.accessKey ?? process.env.CS_CLIENT_ACCESS_KEY,
+            clientId: config3.clientId ?? process.env.CS_CLIENT_ID,
+            clientKey: config3.clientKey ?? process.env.CS_CLIENT_KEY,
             keyset: toFfiKeysetIdentifier(config3.keyset)
           }
         });
         this.encryptConfig = validated;
-        logger.debug("Successfully initialized the Protect.js client.");
+        logger.debug("Successfully initialized the Encryption client.");
         return this;
       },
       (error) => ({
@@ -3958,7 +3965,7 @@ var EncryptionClient = class {
    * Encrypt a value - returns a promise which resolves to an encrypted value.
    *
    * @param plaintext - The plaintext value to be encrypted. Can be null.
-   * @param opts - Options specifying the column and table for encryption.
+   * @param opts - Options specifying the column (or nested field) and table for encryption. See {@link EncryptOptions}.
    * @returns An EncryptOperation that can be awaited or chained with additional methods.
    *
    * @example
@@ -4021,8 +4028,11 @@ var EncryptionClient = class {
    *  .withLockContext(lockContext)
    * ```
    *
+   * @see {@link EncryptOptions}
    * @see {@link Result}
    * @see {@link encryptedTable}
+   * @see {@link encryptedColumn}
+   * @see {@link encryptedField}
    * @see {@link LockContext}
    * @see {@link EncryptOperation}
    */
@@ -4090,10 +4100,16 @@ var EncryptionClient = class {
    * All other fields are passed through unchanged. Returns a thenable operation
    * that supports `.withLockContext()` for identity-aware encryption.
    *
+   * The return type is **schema-aware**: fields matching the table schema are
+   * typed as `Encrypted`, while other fields retain their original types. For
+   * best results, let TypeScript infer the type parameters from the arguments
+   * rather than providing an explicit type argument.
+   *
    * @param input - The model object with plaintext values to encrypt.
    * @param table - The table schema defining which fields to encrypt.
-   * @returns An `EncryptModelOperation<T>` that can be awaited to get a `Result`
-   *   containing the model with encrypted fields, or an `EncryptionError`.
+   * @returns An `EncryptModelOperation` that can be awaited to get a `Result`
+   *   containing the model with schema-defined fields typed as `Encrypted`,
+   *   or an `EncryptionError`.
    *
    * @example
    * ```typescript
@@ -4108,7 +4124,9 @@ var EncryptionClient = class {
    *
    * const client = await Encryption({ schemas: [usersSchema] })
    *
-   * const result = await client.encryptModel<User>(
+   * // Let TypeScript infer the return type from the schema.
+   * // result.data.email is typed as `Encrypted`, result.data.id stays `string`.
+   * const result = await client.encryptModel(
    *   { id: "user_123", email: "alice@example.com", createdAt: new Date() },
    *   usersSchema,
    * )
@@ -4116,13 +4134,17 @@ var EncryptionClient = class {
    * if (result.failure) {
    *   console.error(result.failure.message)
    * } else {
-   *   // result.data.id is unchanged, result.data.email is encrypted
-   *   console.log(result.data)
+   *   console.log(result.data.id)    // string
+   *   console.log(result.data.email) // Encrypted
    * }
    * ```
    */
   encryptModel(input, table) {
-    return new EncryptModelOperation(this.client, input, table);
+    return new EncryptModelOperation(
+      this.client,
+      input,
+      table
+    );
   }
   /**
    * Decrypt a model (object) whose fields contain encrypted values.
@@ -4162,10 +4184,15 @@ var EncryptionClient = class {
    * while still using a unique key for each encrypted value. Only fields
    * matching the table schema are encrypted; other fields pass through unchanged.
    *
+   * The return type is **schema-aware**: fields matching the table schema are
+   * typed as `Encrypted`, while other fields retain their original types. For
+   * best results, let TypeScript infer the type parameters from the arguments.
+   *
    * @param input - An array of model objects with plaintext values to encrypt.
    * @param table - The table schema defining which fields to encrypt.
-   * @returns A `BulkEncryptModelsOperation<T>` that can be awaited to get a `Result`
-   *   containing an array of models with encrypted fields, or an `EncryptionError`.
+   * @returns A `BulkEncryptModelsOperation` that can be awaited to get a `Result`
+   *   containing an array of models with schema-defined fields typed as `Encrypted`,
+   *   or an `EncryptionError`.
    *
    * @example
    * ```typescript
@@ -4180,7 +4207,9 @@ var EncryptionClient = class {
    *
    * const client = await Encryption({ schemas: [usersSchema] })
    *
-   * const result = await client.bulkEncryptModels<User>(
+   * // Let TypeScript infer the return type from the schema.
+   * // Each item's email is typed as `Encrypted`, id stays `string`.
+   * const result = await client.bulkEncryptModels(
    *   [
    *     { id: "1", email: "alice@example.com" },
    *     { id: "2", email: "bob@example.com" },
@@ -4194,7 +4223,11 @@ var EncryptionClient = class {
    * ```
    */
   bulkEncryptModels(input, table) {
-    return new BulkEncryptModelsOperation(this.client, input, table);
+    return new BulkEncryptModelsOperation(
+      this.client,
+      input,
+      table
+    );
   }
   /**
    * Decrypt multiple models (objects) in a single bulk operation.
@@ -4235,7 +4268,7 @@ var EncryptionClient = class {
    * your application data. Null plaintext values are preserved as null.
    *
    * @param plaintexts - An array of objects with `plaintext` (and optional `id`) fields.
-   * @param opts - Options specifying the target column and table for encryption.
+   * @param opts - Options specifying the target column (or nested {@link encryptedField}) and table. See {@link EncryptOptions}.
    * @returns A `BulkEncryptOperation` that can be awaited to get a `Result`
    *   containing an array of `{ id?, data: Encrypted }` objects, or an `EncryptionError`.
    *