chore: update beta branch #1045
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Bumps [@types/superagent](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/superagent) from 8.1.7 to 8.1.8. - [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) - [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/superagent) --- updated-dependencies: - dependency-name: "@types/superagent" dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]>
…superagent-8.1.8 chore(deps-dev): bump @types/superagent from 8.1.7 to 8.1.8
Bumps [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node) from 20.14.0 to 22.0.0. - [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) - [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node) --- updated-dependencies: - dependency-name: "@types/node" dependency-type: direct:development update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]>
style: `ExtendedSchemaMetadata` -> `SchemaTypeInfo`
Bumps [DeterminateSystems/nix-installer-action](https://github.com/determinatesystems/nix-installer-action) from 12 to 13. - [Release notes](https://github.com/determinatesystems/nix-installer-action/releases) - [Commits](DeterminateSystems/nix-installer-action@7993355...ab6bcb2) --- updated-dependencies: - dependency-name: DeterminateSystems/nix-installer-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]>
…rminateSystems/nix-installer-action-13 chore(deps): bump DeterminateSystems/nix-installer-action from 12 to 13
…node-22.0.0 chore(deps-dev): bump @types/node from 20.14.0 to 22.0.0
feat: support array examples at arbitrary levels
Ticket: DX-637
Bumps [memfs](https://github.com/streamich/memfs) from 4.9.4 to 4.11.1. - [Release notes](https://github.com/streamich/memfs/releases) - [Changelog](https://github.com/streamich/memfs/blob/master/CHANGELOG.md) - [Commits](streamich/memfs@v4.9.4...v4.11.1) --- updated-dependencies: - dependency-name: memfs dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]>
…4.11.1 chore(deps-dev): bump memfs from 4.9.4 to 4.11.1
feat: support `domain` for `t.record` codec
feat: support private fields in the openapi generator
feat: consolidate comments from nested levels of schemas
DX-644 This will consolidate t.unknowns when a well defined codec exists in the union, as it presents useless information in our specs and on dev-portal
feat: consolidate unknown unions with well defined codecs
…ers-add-devex-as-code-owners-of-the-github-pages-site chore(codeowners): add DevEx as code owners of the GitHub pages site
I believe openapi-generator's test files were excluded from formatting because back in the day, they used a different format to declare tests and formatting was intrusive. That doesn't seem to apply today, so this commit brings openapi-generator's tests back into the fold (of happily formatted files).
…generator-test-files style: format openapi-generator test files
- Update sidebars.js with explicit category definitions - Modify how-to guides category description - Create reference/explanation category scaffolding - Align documentation structure with Diátaxis framework
- Remove invalid documentation_type field from category configs - Update category descriptions per Diátaxis framework - Fix Tutorials/How-Tos/Reference/Explanation categories - Align with Docusaurus schema requirements
docs: add Diátaxis taxonomy labels to documentation categories
This commit updates our documentation site to use the official `codehike` package (v1.0.5)
instead of the deprecated `@codehike/mdx`. The CodeHike project has consolidated all
functionality into the main `codehike` package, discontinuing support for the separate
`@codehike/mdx` package.
Changes include:
- Updated package.json dependencies to use `codehike@^1.0.5`
- Removed the deprecated `@codehike/mdx` dependency
- Updated import statements in docusaurus.config.js to use the new module path:
`const { remarkCodeHike, recmaCodeHike } = require('codehike/mdx')`
- Replaced the incompatible shiki/nord.json theme with 'github-dark'
- Updated MDX configuration to align with the new CodeHike API
- Adjusted code block syntax in documentation files to work with the new version
This migration ensures our documentation site continues to have proper syntax highlighting
and code examples while staying current with the CodeHike ecosystem. The github-dark theme
provides excellent readability and maintains visual consistency.
chore: nix fix
Ticket: DX-1310 Completely rewrote the Spotlight component implementation to work with CodeHike 1.0.5: - Created a custom React component that renders a side-by-side layout with steps and code - Implemented theme-aware styling that dynamically changes colors based on light/dark mode - Added specific code highlighting for important sections (blue for response, red for errors, green for solutions) - Fixed responsive layout issues with proper wrapping and minimum widths - Added transition effects for smoother theme switching This change specifically updates the intermediate-semantic-analysis.md documentation file while maintaining the same educational content and interactive experience from codehike/mdx version 0.9.0. chore(website): Remove unused variable
feat(docs): spotlight component for an article
Introduces initial Docusaurus documentation files (.mdx) for key components of the `@api-ts/io-ts-http` package, including: `apiSpec`, `httpRoute`, `httpRequest`, `GenericHttpRequest`, `flattened`, `optional`, and `optionalize`. This is part of the effort to consolidate fragmented documentation (READMEs, Confluence, etc.) into a single source of truth on the new Docusaurus website. chore: add vivian's feedback
feat(docs): Add core @api-ts/io-ts-http docs to Docusaurus
… format
This commit significantly refactors the documentation for the `@api-ts/openapi-generator` package to align with the Reference section principles of the Diátaxis framework. The goal is to provide users with a clear, structured, and authoritative technical description suitable for direct consultation during development.
**Key Changes:**
* Restructured the entire README.md into a dedicated Reference section, replacing the previous narrative format.
* Organized content into logical subsections for improved navigability and focus:
* **Command-Line Interface (CLI):** Provides a technical overview, usage syntax, and detailed descriptions of the `<file>` argument, options (`--name`, `--version`, `--codec-file`), and flags (`--internal`, `--help`), along with concrete usage examples.
* **Configuration:** Clearly documents the requirements for preparing external types packages (specifying `files` and `source` in the external package's `package.json`). Details the two distinct methods for defining custom codec schemas:
1. Via `openapi-gen.config.js` within the types package (recommended for type authors), including file naming, `package.json` requirements (`customCodecFile`, `files`), and file structure.
2. Via the `--codec-file` CLI option for consumers, specifying the required file structure (grouping by package name).
* **Supported `io-ts` Primitives:** Includes a definitive list of `io-ts` primitives and combinators that the generator can automatically interpret to produce OpenAPI schemas.
* **JSDoc Annotations:** Exhaustively documents the supported JSDoc tags used to enrich the generated OpenAPI specification, categorized by:
* *Endpoint Annotations* (applied to `httpRoute` variables): Covers Summary, Description, `@operationId`, `@tag`, `@private`, `@unstable`, `@example`, and the handling of unknown tags (`x-unknown-tags`), explaining their direct mapping to OpenAPI Operation Object fields (like `summary`, `description`, `operationId`, `tags`, `x-internal`, `x-unstable`, `example`, `x-unknown-tags`).
* *Schema Annotations* (applied to `io-ts` types/fields): Details how to add descriptions via JSDoc text and lists all supported standard OpenAPI tags (`@default`, `@example`, `@minLength`, `@maximum`, `@pattern`, `@format`, etc.) and custom tags (`@private`, `@deprecated`), explaining their effect on the resulting OpenAPI Schema Object or Property (like `description`, `default`, `minLength`, `deprecated`, `x-internal`). Includes comprehensive examples demonstrating tag usage.
* Removed introductory explanations and narrative prose, focusing strictly on factual, technical descriptions of the tool's features, configuration requirements, and behavior based on inputs (like JSDoc tags).
**Impact:**
This restructuring provides developers using `@api-ts/openapi-generator` with significantly improved technical reference documentation. The information is now presented in a consistent, predictable, and easily searchable format, adhering to the Diátaxis framework's guidelines for effective reference material. This makes it easier for users to find the specific technical details they need regarding CLI usage, configuration, supported types, and JSDoc annotation capabilities while working with the generator.
chore: apply feedback
chore: fix heading to use title casing
chore: add . after sentences
chore: apply feedback
docs(openapi-generator): Refactor documentation to Diátaxis Reference format
…ence section
This commit refactors the documentation for the `@api-ts/superagent-wrapper` package, migrating technical details from the main README into a dedicated, structured Reference section following the Diátaxis framework.
**Motivation:**
The previous documentation, while providing a getting started guide, lacked a formal, easily navigable technical reference for the package's core components. Users needing specific details about function signatures, parameters, return types, or the structure of the generated API client had to infer them from the narrative guide and examples. Adopting the Diátaxis framework provides a standardized, clear structure for technical information, improving user experience and maintainability.
**Changes Implemented:**
1. **Established Diátaxis Reference Structure:** Created a new documentation structure under `docs/reference/superagent-wrapper/` specifically for reference material.
2. **Component-Based File Organization:** Split the reference documentation into multiple MDX files, each focusing on a distinct component or concept:
* `index.mdx`: Provides an overview and entry point for the `@api-ts/superagent-wrapper` reference section.
* `superagent-request-factory.mdx`: Contains the detailed technical reference for the `superagentRequestFactory` function.
* `supertest-request-factory.mdx`: Contains the detailed technical reference for the `supertestRequestFactory` function.
* `build-api-client.mdx`: Contains the detailed technical reference for the `buildApiClient` function.
* `api-client.mdx`: Provides a comprehensive description of the structure of the `ApiClient` object returned by `buildApiClient`, including its operation methods, the `PreparedRequest` methods (`.decode()`, `.decodeExpecting()`), and the structure of the `ApiResponse`/`SpecificApiResponse` objects.
3. **Content Migration and Enhancement:** Extracted technical details and examples from the original README and rewrote them into formal reference documentation. This includes:
* Precise descriptions of each function's purpose.
* Clear representation of function signatures (including conceptual type definitions where applicable).
* Detailed breakdown of parameters and return values.
* Technical explanation of the generated `ApiClient` object's structure and behavior.
* Explicit documentation of the `.decode()` and `.decodeExpecting()` methods and the response objects they return, including notes on type narrowing.
**Benefits (Impact on Users):**
* **Improved Findability:** Users can now directly navigate to the specific component they need information about (e.g., `buildApiClient`, `.decode()`).
* **Enhanced Clarity:** Provides clear, unambiguous technical descriptions separate from narrative guides.
* **Better Organization:** Structured according to a well-regarded documentation framework (Diátaxis).
* **Increased Detail:** Offers more explicit information on signatures, types, and the behavior of the generated client than was previously available.
* **Consistency:** Aligns the documentation approach with other packages potentially using the same framework (e.g., `@api-ts/io-ts-http`).
This restructuring significantly improves the quality and usability of the technical documentation for `@api-ts/superagent-wrapper`.
…rence section
This commit significantly restructures and enhances the documentation for the `@api-ts/typed-express-router` package by adopting the Diátaxis framework and creating a dedicated, multi-file Reference section.
**Motivation:**
The previous documentation, primarily located in the README, mixed introductory guides with technical details. This made it difficult for users to quickly find precise information about specific functions, types, or configuration options without reading through narrative content. A formal Reference section, following Diátaxis principles, provides a much clearer, more accessible, and maintainable structure for technical documentation.
**Changes Implemented:**
1. **Diátaxis Reference Structure:** Established a dedicated directory (`docs/reference/typed-express-router/`) for technical reference material, separating it from other documentation types (like Tutorials or How-To Guides, which might exist elsewhere).
2. **Component-Focused File Organization:** Divided the reference documentation into distinct MDX files, each dedicated to a specific component or concept of the library:
* `index.mdx`: Serves as the entry point and overview for the typed-express-router reference section.
* `create-router.mdx`: Details the `createRouter` function.
* `wrap-router.mdx`: Details the `wrapRouter` function.
* `typed-router.mdx`: Describes the `TypedRouter` object itself, including its typed route methods (e.g., `.get`, `.getUnchecked`) and middleware handling (`.use`).
* `request-response.mdx`: Explains the augmented `req` (with `req.decoded`) and `res` (with `res.sendEncoded`) objects provided to route handlers.
* `configuration.mdx`: Documents the global (`TypedRouterOptions`) and per-route (`RouteOptions`) configuration, including error hooks (`onDecodeError`, `onEncodeError`), the post-response hook (`afterEncodedResponseSent`), and `routeAliases`.
* `typed-request-handler.mdx`: Describes the `TypedRequestHandler` helper type for improved type safety in handler definitions.
3. **Content Migration & Refinement:** Technical information previously embedded in the README's "Usage" section has been extracted, expanded, and reformatted into precise reference documentation within the new structure. This includes:
* Clear function/type signatures.
* Detailed descriptions of parameters and return values.
* Explicit explanations of component behavior (e.g., checked vs. unchecked routes, hook triggering conditions).
* Code examples focused on illustrating the specific component being documented.
**Benefits (Impact on Users & Maintainers):**
* **Improved Discoverability:** Users needing technical details about `createRouter`, `req.decoded`, configuration hooks, or other specific features can now find dedicated pages quickly.
* **Enhanced Clarity & Precision:** Technical specifications are presented directly and unambiguously, separate from introductory narratives.
* **Better Maintainability:** Isolating documentation for each component makes future updates easier and less error-prone.
* **Standardized Structure:** Adopts a recognized documentation pattern (Diátaxis), improving consistency potentially across multiple related packages.
* **Increased Comprehensiveness:** Provides more explicit detail on the library's features and types than previously available in the consolidated README.
This refactoring represents a significant improvement in the quality, usability, and maintainability of the `@api-ts/typed-express-router` technical documentation.
docs(superagent-wrapper): Restructure documentation as Diátaxis
docs(typed-express-router): Refactor documentation into Diátaxis Reference section
style: apply prettier
DevEx owns all things APIs, so this is a natural fit, now that the team has support to take on maintenance. Closes Ticket: DX-1472
…r-code-ownership-to-devex chore: transfer code ownership to DevEx
I'm not an expert here, but I think there's some weird behavior if you rebase the |
|
Closing this branch because we took an alternate approach. First we deleted the beta branch on GitHub, then we pushed master to beta from our local git CLI. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Ticket: DX-1518
This PR rebases the beta branch with the master.