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,