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

[coderdan]

Why

The docs deploy (TypeDoc reference, built by cipherstash/docs) emits a large batch of warnings for @cipherstash/stack. The bulk of them are TSDoc {@link} cross-references and method return types that point at operation classes / types that aren't part of the documented public surface, so TypeDoc can't link them.

This PR fixes the stack-side half: the symbols those comments reference are now genuinely public, so the links resolve to real reference pages. The companion docs-repo PR handles the build-config half (external-symbol mappings, the errors entry point, and silencing genuinely-internal referenced types).

What changed

• Export the operation classes returned by public methods so they're documented:
  • @cipherstash/stack/encryption: EncryptOperation, EncryptQueryOperation, BatchEncryptQueryOperation, DecryptOperation, EncryptModelOperation, DecryptModelOperation, BulkEncryptOperation, BulkDecryptOperation, BulkEncryptModelsOperation, BulkDecryptModelsOperation
  • @cipherstash/stack/dynamodb: EncryptModelOperation, DecryptModelOperation, BulkEncryptModelsOperation, BulkDecryptModelsOperation
  • @cipherstash/stack/types: EncryptedQuery, EncryptedFromSchema
• EncryptQueryOperation / BatchEncryptQueryOperation are no longer @internal — they're returned from encryptQuery, so they're now public for consistency with the other operations. The *WithLockContext variants stay internal.
• TSDoc fixes so links resolve: type-only imports for LockContext and the encryptedTable/Column/Field helpers, reworded the EncryptionClient.init reference (it's @internal), and corrected buildEncryptConfig's @param name.

Notes

• No runtime behaviour change — this only widens the exported surface and corrects comments. Changeset included (minor bump).
• Verified locally by running the docs repo's TypeDoc against this branch together with the docs-repo PR: 0 warnings / 0 errors (down from 54), with every previously-broken link resolving to a real page.
• The reference only regenerates against release tags, so the docs go fully clean once a stack version including these exports is released (this PR should land/release ahead of relying on the docs PR).

Summary by CodeRabbit

• New Features

  • Operation result types are now publicly exported for TypeScript reference, including Encrypt, Decrypt, query, model, and bulk operation variants.

• Documentation

  • Enhanced TSDoc documentation with improved type reference resolution and clarified API surface visibility.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6e7ae4e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@cipherstash/stack	Minor
@cipherstash/bench	Patch
@cipherstash/prisma-next	Patch
@cipherstash/basic-example	Patch
@cipherstash/prisma-next-example	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 38564b12-d077-4a0f-9e29-2b1e44057daa

📥 Commits

Reviewing files that changed from the base of the PR and between b9c4fe5 and 6e7ae4e.

📒 Files selected for processing (8)

• .changeset/export-operation-result-types.md
• packages/stack/src/dynamodb/index.ts
• packages/stack/src/encryption/index.ts
• packages/stack/src/encryption/operations/batch-encrypt-query.ts
• packages/stack/src/encryption/operations/encrypt-query.ts
• packages/stack/src/schema/index.ts
• packages/stack/src/types-public.ts
• packages/stack/src/types.ts

💤 Files with no reviewable changes (2)

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

---

📝 Walkthrough

Walkthrough

This PR widens the public API surface by exporting operation result classes returned from encryption and DynamoDB client methods, removes internal markers from query operations, and adds supporting type imports to resolve TypeScript type references and TSDoc documentation links.

Changes

Operation type exports and documentation

Layer / File(s)	Summary
Changeset documentation .changeset/export-operation-result-types.md	Records the public API change: operation result classes are now exported so TypeScript can reference their types and TSDoc links resolve correctly.
Encryption module operation exports packages/stack/src/encryption/index.ts, packages/stack/src/encryption/operations/batch-encrypt-query.ts	Encryption module re-exports operation classes (EncryptOperation, EncryptQueryOperation, BatchEncryptQueryOperation, DecryptOperation, and bulk/model variants) as public API; @internal markers removed from query operation classes.
DynamoDB module operation exports packages/stack/src/dynamodb/index.ts	DynamoDB module re-exports model and bulk operation classes (EncryptModelOperation, DecryptModelOperation, BulkEncryptModelsOperation, BulkDecryptModelsOperation) as public API.
Type re-exports for public API packages/stack/src/types-public.ts	Core types EncryptedQuery and EncryptedFromSchema are added to the public type re-export list.
TSDoc link resolution and documentation packages/stack/src/encryption/index.ts, packages/stack/src/types.ts, packages/stack/src/schema/index.ts	Type-only imports for LockContext, schema entities, and schema types are added to enable {@link ...} references in documentation. JSDoc parameter name is corrected in buildEncryptConfig and Encryption function's error description is clarified.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• calvinbrewer
• auxesis

Poem

🐰 Types now shine in public light,
No more shadows, all TSDoc links are right,
Query ops emerge from internal shroud,
Schema dances, type references proud,
Documentation fixed, the API's proud!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: exporting operation classes from public methods, which is the primary focus across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/export-operation-classes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}