Merge pull request #502 from cipherstash/feat/export-operation-classes

feat(stack): export operation classes returned by public methods

Author: coderdan

.changeset/export-operation-result-types.md

@@ -0,0 +1,15 @@
+---
+"@cipherstash/stack": minor
+---
+
+Export the operation classes returned by the encryption and DynamoDB clients as public API.
+
+The classes returned from public methods are now exported and documented in the API reference, so their types can be named and their TSDoc links resolve.
+
+- From `@cipherstash/stack/encryption`: `EncryptOperation`, `EncryptQueryOperation`, `BatchEncryptQueryOperation`, `DecryptOperation`, `EncryptModelOperation`, `DecryptModelOperation`, `BulkEncryptOperation`, `BulkDecryptOperation`, `BulkEncryptModelsOperation`, `BulkDecryptModelsOperation`. `EncryptQueryOperation` and `BatchEncryptQueryOperation` were previously marked `@internal`; since they are returned from `EncryptionClient.encryptQuery`, they are now public for consistency with the other operations.
+- From `@cipherstash/stack/dynamodb`: `EncryptModelOperation`, `DecryptModelOperation`, `BulkEncryptModelsOperation`, `BulkDecryptModelsOperation`.
+- From `@cipherstash/stack/types`: `EncryptedQuery` and `EncryptedFromSchema`.
+
+The `*WithLockContext` variants returned by `.withLockContext()` remain internal — they share the same awaitable shape and are not intended to be named directly.
+
+No runtime behaviour changes; this only widens the exported surface and corrects TSDoc cross-references that previously failed to resolve.

packages/stack/src/dynamodb/index.ts

@@ -97,3 +97,12 @@ export type {
   EncryptedDynamoDBError,
   EncryptedDynamoDBInstance,
 } from './types'
+
+// Re-export the operation classes returned by the DynamoDB instance methods so
+// they are part of the public API and appear in the generated reference.
+export {
+  EncryptModelOperation,
+  DecryptModelOperation,
+  BulkEncryptModelsOperation,
+  BulkDecryptModelsOperation,
+}

packages/stack/src/encryption/index.ts

@@ -1,10 +1,17 @@
 import { type EncryptionError, EncryptionErrorTypes } from '@/errors'
+// `LockContext` is imported type-only so the TSDoc {@link} references in the
+// comments below resolve; it is erased at compile time.
+import type { LockContext } from '@/identity'
 import {
   type EncryptConfig,
   type EncryptedTable,
   type EncryptedTableColumn,
   buildEncryptConfig,
   encryptConfigSchema,
+  // Imported type-only for the TSDoc {@link} references in the comments below.
+  type encryptedColumn,
+  type encryptedField,
+  type encryptedTable,
 } from '@/schema'
 import type {
   BulkDecryptPayload,
@@ -35,6 +42,22 @@ import { EncryptOperation } from './operations/encrypt'
 import { EncryptModelOperation } from './operations/encrypt-model'
 import { EncryptQueryOperation } from './operations/encrypt-query'
 
+// Re-export the operation classes returned by EncryptionClient methods so they
+// are part of the public API and appear in the generated reference, allowing
+// TSDoc {@link} references and method return types to resolve to real pages.
+export {
+  EncryptOperation,
+  EncryptQueryOperation,
+  BatchEncryptQueryOperation,
+  DecryptOperation,
+  EncryptModelOperation,
+  DecryptModelOperation,
+  BulkEncryptOperation,
+  BulkDecryptOperation,
+  BulkEncryptModelsOperation,
+  BulkDecryptModelsOperation,
+}
+
 export const noClientError = () =>
   new Error(
     'The Encryption client has not been initialized. Please call init() before using the client.',
@@ -610,7 +633,7 @@ export class EncryptionClient {
  *   {@link EncryptionClient.encrypt}, {@link EncryptionClient.decrypt}, and related operations.
  *
  * @throws Throws if `schemas` is empty, or if a keyset `id` is supplied but is not a valid UUID.
- *   Also throws if {@link EncryptionClient.init} fails (e.g. invalid credentials or config).
+ *   Also throws if the client fails to initialize (e.g. invalid credentials or config).
  *
  * @example
  * ```typescript

packages/stack/src/encryption/operations/batch-encrypt-query.ts

@@ -91,9 +91,6 @@ function assembleResults(
   return results
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with array input instead.
- */
 export class BatchEncryptQueryOperation extends EncryptionOperation<
   EncryptedQueryResult[]
 > {
@@ -168,9 +165,6 @@ export class BatchEncryptQueryOperation extends EncryptionOperation<
   }
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with array input and `.withLockContext()` instead.
- */
 export class BatchEncryptQueryOperationWithLockContext extends EncryptionOperation<
   EncryptedQueryResult[]
 > {

packages/stack/src/encryption/operations/encrypt-query.ts

@@ -17,9 +17,6 @@ import {
 import { noClientError } from '../index'
 import { EncryptionOperation } from './base-operation'
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} instead.
- */
 export class EncryptQueryOperation extends EncryptionOperation<EncryptedQueryResult> {
   constructor(
     private client: Client,
@@ -114,9 +111,6 @@ export class EncryptQueryOperation extends EncryptionOperation<EncryptedQueryRes
   }
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with `.withLockContext()` instead.
- */
 export class EncryptQueryOperationWithLockContext extends EncryptionOperation<EncryptedQueryResult> {
   constructor(
     private client: Client,

packages/stack/src/schema/index.ts

@@ -658,7 +658,7 @@ export function encryptedField(valueName: string) {
 /**
  * Build an encrypt config from a list of encrypted tables.
  *
- * @param ...tables - The list of encrypted tables to build the config from.
+ * @param protectTables - The list of encrypted tables to build the config from.
  * @returns An encrypt config object.
  *
  * @example

packages/stack/src/types-public.ts

@@ -11,6 +11,7 @@ export type {
   Client,
   EncryptedValue,
   Encrypted,
+  EncryptedQuery,
 } from '@/types'
 
 // Client configuration
@@ -35,6 +36,7 @@ export type {
   OtherFields,
   DecryptedFields,
   Decrypted,
+  EncryptedFromSchema,
 } from '@/types'
 
 // Bulk operations

packages/stack/src/types.ts

@@ -3,6 +3,9 @@ import type {
   EncryptedField,
   EncryptedTable,
   EncryptedTableColumn,
+  // Imported type-only for the TSDoc {@link} references in the comments below.
+  encryptedColumn,
+  encryptedField,
 } from '@/schema'
 import type {
   Encrypted as CipherStashEncrypted,