From 6e7ae4e117c4847b62491d63da8df5e74b4a5bc9 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 2 Jun 2026 10:55:27 +1000 Subject: [PATCH] feat(stack): export operation classes returned by public methods Export the operation classes returned by the encryption and DynamoDB clients (plus EncryptedQuery and EncryptedFromSchema) so they are part of the public API and appear in the generated TypeDoc reference. This makes the TSDoc {@link} cross-references and method return types resolve to real pages instead of failing to resolve or pointing at undocumented symbols. - encryption: Encrypt/EncryptQuery/Decrypt/Bulk*/*Model* operation classes - dynamodb: model operation classes - types: EncryptedQuery, EncryptedFromSchema - EncryptQueryOperation / BatchEncryptQueryOperation are no longer @internal, for consistency with the other operations (they are returned from encryptQuery) - add type-only imports for {@link} resolution; fix the init reference and a buildEncryptConfig @param name --- .changeset/export-operation-result-types.md | 15 +++++++++++ packages/stack/src/dynamodb/index.ts | 9 +++++++ packages/stack/src/encryption/index.ts | 25 ++++++++++++++++++- .../operations/batch-encrypt-query.ts | 6 ----- .../encryption/operations/encrypt-query.ts | 6 ----- packages/stack/src/schema/index.ts | 2 +- packages/stack/src/types-public.ts | 2 ++ packages/stack/src/types.ts | 3 +++ 8 files changed, 54 insertions(+), 14 deletions(-) create mode 100644 .changeset/export-operation-result-types.md diff --git a/.changeset/export-operation-result-types.md b/.changeset/export-operation-result-types.md new file mode 100644 index 00000000..cee74560 --- /dev/null +++ b/.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. diff --git a/packages/stack/src/dynamodb/index.ts b/packages/stack/src/dynamodb/index.ts index caffa411..f6bbb830 100644 --- a/packages/stack/src/dynamodb/index.ts +++ b/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, +} diff --git a/packages/stack/src/encryption/index.ts b/packages/stack/src/encryption/index.ts index bad58542..1a92c562 100644 --- a/packages/stack/src/encryption/index.ts +++ b/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 diff --git a/packages/stack/src/encryption/operations/batch-encrypt-query.ts b/packages/stack/src/encryption/operations/batch-encrypt-query.ts index 0e2b674b..661e2290 100644 --- a/packages/stack/src/encryption/operations/batch-encrypt-query.ts +++ b/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[] > { diff --git a/packages/stack/src/encryption/operations/encrypt-query.ts b/packages/stack/src/encryption/operations/encrypt-query.ts index f013d1f7..85fb57ac 100644 --- a/packages/stack/src/encryption/operations/encrypt-query.ts +++ b/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 { constructor( private client: Client, @@ -114,9 +111,6 @@ export class EncryptQueryOperation extends EncryptionOperation { constructor( private client: Client, diff --git a/packages/stack/src/schema/index.ts b/packages/stack/src/schema/index.ts index 6aa9be89..70285bd3 100644 --- a/packages/stack/src/schema/index.ts +++ b/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 diff --git a/packages/stack/src/types-public.ts b/packages/stack/src/types-public.ts index 80b28985..fead33ea 100644 --- a/packages/stack/src/types-public.ts +++ b/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 diff --git a/packages/stack/src/types.ts b/packages/stack/src/types.ts index 87a71dea..39bdec77 100644 --- a/packages/stack/src/types.ts +++ b/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,