hono-takibi 0.0.1

package/README.md

@@ -0,0 +1,471 @@
+![img](assets/icon/hono-takibi.png)
+
+# Hono Takibi
+
+![img](assets/img/hono-takibi.png)
+
+## Migrate Legacy APIs to Hono
+
+**Hono Takibi** is an OpenAPI-to-Hono code generator, specifically developed to assist in migrating APIs from various programming languages to Hono. This tool automates the creation of type-safe Hono routes from your existing OpenAPI specifications, making it easier to transition from legacy systems (Ruby, Perl, PHP, etc.) to a modern Hono architecture.
+
+## What Problem Does It Solve?
+
+Moving to [Zod OpenAPI Hono](https://hono.dev/examples/zod-openapi) requires:
+
+* Manual conversion of OpenAPI paths to Hono routes
+* Translation of OpenAPI schemas to Zod schemas
+* Implementation of type-safe request/response handling
+
+If you have OpenAPI specifications, Hono Takibi automates the conversion process to [@hono/zod-openapi](https://github.com/honojs/middleware/tree/main/packages/zod-openapi), allowing you to focus on implementing your business logic rather than dealing with boilerplate code. While we aim for full compatibility in the generated code, we're continuously working to improve the conversion accuracy and support more OpenAPI features. We welcome feedback and contributions to make this tool even better for the community.
+
+**Hono Takibi** automates this process by:
+- Converting OpenAPI schemas to Zod schemas
+- Generating type-safe route definitions
+- Creating proper variable names and exports
+
+```bash
+npm add -D hono-takibi
+```
+
+# Usage
+
+```bash
+npx hono-takibi path/to/input.yaml -o path/to/output.ts
+```
+
+# Example
+
+```bash
+npx hono-takibi example/hono-rest-example.yaml -o routes/index.ts
+```
+
+input:
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Hono API
+  version: v1
+
+components:
+  schemas:
+    Error:
+      type: object
+      properties:
+        message:
+          type: string
+      required:
+        - message
+    Post:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier of the post
+        post:
+          type: string
+          description: Content of the post
+          minLength: 1
+          maxLength: 140
+        createdAt:
+          type: string
+          format: date-time
+          description: Timestamp when the post was created
+        updatedAt:
+          type: string
+          format: date-time
+          description: Timestamp when the post was last updated
+      required:
+        - id
+        - post
+        - createdAt
+        - updatedAt
+
+tags:
+  - name: Hono
+    description: Endpoints related to general Hono operations
+  - name: Post
+    description: Endpoints for creating, retrieving, updating, and deleting posts
+
+paths:
+  /:
+    get:
+      tags:
+        - Hono
+      summary: Welcome message
+      description: Retrieve a simple welcome message from the Hono API.
+      responses:
+        '200':
+          description: Successful response with a welcome message.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Hono🔥
+                required:
+                  - message
+
+  /posts:
+    post:
+      tags:
+        - Post
+      summary: Create a new post
+      description: Submit a new post with a maximum length of 140 characters.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                post:
+                  type: string
+                  description: Content of the post
+                  minLength: 1
+                  maxLength: 140
+              required:
+                - post
+            example:
+              post: "This is my first post!"
+      responses:
+        '201':
+          description: Post successfully created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: Created
+        '400':
+          description: Invalid request due to bad input.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: Post content is required and must be between 1 and 140 characters.
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: An unexpected error occurred. Please try again later.
+
+    get:
+      tags:
+        - Post
+      summary: Retrieve a list of posts
+      description: Retrieve a paginated list of posts. Specify the page number and the number of posts per page.
+      parameters:
+        - in: query
+          name: page
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+          description: The page number to retrieve. Must be a positive integer. Defaults to 1.
+        - in: query
+          name: rows
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            default: 10
+          description: The number of posts per page. Must be a positive integer. Defaults to 10.
+      responses:
+        '200':
+          description: Successfully retrieved a list of posts.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Post'
+              example:
+                - id: "123e4567-e89b-12d3-a456-426614174000"
+                  post: "Hello world!"
+                  createdAt: "2024-12-01T12:34:56Z"
+                  updatedAt: "2024-12-02T14:20:00Z"
+        '400':
+          description: Invalid request due to bad input.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: Invalid page or rows parameter. Both must be positive integers.
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: An unexpected error occurred. Please try again later.
+
+  /posts/{id}:
+    put:
+      tags:
+        - Post
+      summary: Update an existing post
+      description: Update the content of an existing post identified by its unique ID.
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: Unique identifier of the post.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                post:
+                  type: string
+                  description: Updated content for the post
+                  minLength: 1
+                  maxLength: 140
+              required:
+                - post
+            example:
+              post: "Updated post content."
+      responses:
+        '204':
+          description: Post successfully updated.
+        '400':
+          description: Invalid input.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: Post content is required and must be between 1 and 140 characters.
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: An unexpected error occurred. Please try again later.
+
+    delete:
+      tags:
+        - Post
+      summary: Delete a post
+      description: Delete an existing post identified by its unique ID.
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: Unique identifier of the post.
+      responses:
+        '204':
+          description: Post successfully deleted.
+        '400':
+          description: Invalid input.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: Invalid post ID.
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: An unexpected error occurred. Please try again later.
+```
+
+output:
+
+```ts
+import { createRoute, z } from '@hono/zod-openapi'
+
+const errorSchema = z.object({ message: z.string() })
+
+const postSchema = z.object({
+  id: z.string().uuid(),
+  post: z.string().min(1).max(140),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+})
+
+export const schemas = {
+  errorSchema,
+  postSchema,
+}
+
+export const getRoute = createRoute({
+  tags: ['Hono'],
+  method: 'get',
+  path: '/',
+  description: 'Retrieve a simple welcome message from the Hono API.',
+  responses: {
+    200: {
+      description: 'Successful response with a welcome message.',
+      content: { 'application/json': { schema: z.object({ message: z.string() }) } },
+    },
+  },
+})
+
+export const postPostsRoute = createRoute({
+  tags: ['Post'],
+  method: 'post',
+  path: '/posts',
+  description: 'Submit a new post with a maximum length of 140 characters.',
+  request: {
+    body: {
+      required: true,
+      content: { 'application/json': { schema: z.object({ post: z.string().min(1).max(140) }) } },
+    },
+  },
+  responses: {
+    201: {
+      description: 'Post successfully created.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+    400: {
+      description: 'Invalid request due to bad input.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+    500: {
+      description: 'Internal server error.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+  },
+})
+
+export const getPostsRoute = createRoute({
+  tags: ['Post'],
+  method: 'get',
+  path: '/posts',
+  description:
+    'Retrieve a paginated list of posts. Specify the page number and the number of posts per page.',
+  request: {
+    query: z.object({
+      page: z.string().pipe(z.coerce.number().int().min(0)).optional(),
+      rows: z.string().pipe(z.coerce.number().int().min(0)).optional(),
+    }),
+  },
+  responses: {
+    200: {
+      description: 'Successfully retrieved a list of posts.',
+      content: { 'application/json': { schema: z.array(postSchema) } },
+    },
+    400: {
+      description: 'Invalid request due to bad input.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+    500: {
+      description: 'Internal server error.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+  },
+})
+
+export const putPostsIdRoute = createRoute({
+  tags: ['Post'],
+  method: 'put',
+  path: '/posts/{id}',
+  description: 'Update the content of an existing post identified by its unique ID.',
+  request: {
+    body: {
+      required: true,
+      content: { 'application/json': { schema: z.object({ post: z.string().min(1).max(140) }) } },
+    },
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    204: { description: 'Post successfully updated.' },
+    400: {
+      description: 'Invalid input.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+    500: {
+      description: 'Internal server error.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+  },
+})
+
+export const deletePostsIdRoute = createRoute({
+  tags: ['Post'],
+  method: 'delete',
+  path: '/posts/{id}',
+  description: 'Delete an existing post identified by its unique ID.',
+  request: { params: z.object({ id: z.string().uuid() }) },
+  responses: {
+    204: { description: 'Post successfully deleted.' },
+    400: {
+      description: 'Invalid input.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+    500: {
+      description: 'Internal server error.',
+      content: { 'application/json': { schema: errorSchema } },
+    },
+  },
+})
+```
+
+## ⚠️ Development Status
+
+This project is in **early development** and being maintained by a developer with about 2 years of experience. While I'm doing my best to create a useful tool:
+
+We welcome feedback and contributions to improve the tool!
+
+### Current Limitations
+
+1. **Schema Naming Convention**
+   - Only generates camelCase schema names
+   - Example: `Post` in OpenAPI becomes `postSchema` in generated code
+   - No support for custom naming conventions yet
+
+2. **OpenAPI Support**
+   - Not all OpenAPI features are supported
+   - Complex schemas might not convert correctly
+   - Limited support for certain response types
+   - Some OpenAPI validations may not be perfectly converted to Zod validations
+
+### 🙏 Seeking Advice
+
+As a relatively new developer, I would greatly appreciate feedback on:
+
+- Code architecture and best practices
+- Error handling approaches
+- Testing strategies
+- Performance improvements
+- Security considerations
+- Naming convention flexibility
+- OpenAPI to Zod conversion strategies
+
+I welcome any feedback, suggestions, or contributions that could help make this tool more robust and reliable. Feel free to:
+- Open issues for bugs or suggestions
+- Submit PRs with improvements
+- Share your experience using the tool
+- Provide guidance on better coding practices
+- Report any conversion inconsistencies you find
+
+Let's make this tool better together! 🔥
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita-Ypm/hono-takibi?tab=MIT-1-ov-file) for more information.

package/dist/core/schema/references/find-references.d.ts

@@ -0,0 +1,35 @@
+import type { Schema } from '../../../types';
+/**
+ * Collects all $ref references from an OpenAPI schema by recursively traversing it
+ *
+ * @function findReferences
+ * @param schema - The OpenAPI schema to search for references
+ * @returns A Set of strings containing all schema names referenced via $ref
+ *
+ * @example
+ * const schema = {
+ *   type: 'object',
+ *   properties: {
+ *     tags: {
+ *       type: 'array',
+ *       items: {
+ *         $ref: '#/components/schemas/Tag'
+ *       }
+ *     },
+ *     category: {
+ *       $ref: '#/components/schemas/Category'
+ *     }
+ *   }
+ * }
+ *
+ * const refs = findReferences(schema)
+ * // refs contains: Set { 'Tag', 'Category' }
+ *
+ * @note
+ * - Extracts only the schema name from $ref paths
+ *   e.g., '#/components/schemas/Tag' becomes 'Tag'
+ * - Recursively traverses all properties in the schema
+ * - Automatically deduplicates references via Set
+ * - Handles nested references in arrays and objects
+ */
+export declare function findReferences(schema: Schema): Set<string>;

package/dist/core/schema/references/find-references.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findReferences = findReferences;
+const traverse_schema_1 = require("./traverse_schema");
+/**
+ * Collects all $ref references from an OpenAPI schema by recursively traversing it
+ *
+ * @function findReferences
+ * @param schema - The OpenAPI schema to search for references
+ * @returns A Set of strings containing all schema names referenced via $ref
+ *
+ * @example
+ * const schema = {
+ *   type: 'object',
+ *   properties: {
+ *     tags: {
+ *       type: 'array',
+ *       items: {
+ *         $ref: '#/components/schemas/Tag'
+ *       }
+ *     },
+ *     category: {
+ *       $ref: '#/components/schemas/Category'
+ *     }
+ *   }
+ * }
+ *
+ * const refs = findReferences(schema)
+ * // refs contains: Set { 'Tag', 'Category' }
+ *
+ * @note
+ * - Extracts only the schema name from $ref paths
+ *   e.g., '#/components/schemas/Tag' becomes 'Tag'
+ * - Recursively traverses all properties in the schema
+ * - Automatically deduplicates references via Set
+ * - Handles nested references in arrays and objects
+ */
+function findReferences(schema) {
+    const refs = new Set();
+    (0, traverse_schema_1.traverseSchema)(schema, refs);
+    return refs;
+}

package/dist/core/schema/references/get-camel-case-schema-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generates a camelCase schema name from a given schema name.
+ *
+ * @param schemaName - The original schema name.
+ * @returns The camelCase schema name.
+ */
+export declare function getCamelCaseSchemaName(schemaName: string): string;

package/dist/core/schema/references/get-camel-case-schema-name.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCamelCaseSchemaName = getCamelCaseSchemaName;
+const decapitalize_1 = require("../../text/decapitalize");
+/**
+ * Generates a camelCase schema name from a given schema name.
+ *
+ * @param schemaName - The original schema name.
+ * @returns The camelCase schema name.
+ */
+function getCamelCaseSchemaName(schemaName) {
+    const decapitalizedSchemaName = (0, decapitalize_1.decapitalize)(schemaName);
+    return `${decapitalizedSchemaName}Schema`;
+}

package/dist/core/schema/references/get-ref-name.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Extracts the type name from an OpenAPI schema reference ($ref)
+ *
+ * @function getRefName
+ * @param ref - OpenAPI schema reference path (e.g., '#/components/schemas/Address')
+ * @returns The referenced type name, or undefined if the reference is invalid
+ *
+ * @example
+ * // Basic usage with Address schema
+ * getRefName('#/components/schemas/Address')
+ * // Returns: 'Address'
+ *
+ * // Nested Address schema
+ * getRefName('#/components/schemas/Location/Address')
+ * // Returns: 'Address'
+ *
+ * // Complex Address reference
+ * getRefName('#/components/schemas/Shipping/Address/Details')
+ * // Returns: 'Details'
+ *
+ * // Invalid path
+ * getRefName('')
+ * // Returns: undefined
+ *
+ * @note
+ * - Expects standard OpenAPI reference paths (e.g., '#/components/schemas/Address')
+ * - Extracts the last segment of the path as the type name
+ * - Returns undefined for empty strings or invalid paths
+ * - Used when processing Address and other schema references in OpenAPI
+ *
+ * @description
+ * Processes OpenAPI $ref strings to extract schema type names.
+ * For example, when processing an Address schema reference:
+ * Input: '#/components/schemas/Address'
+ * Process: Splits by '/' -> ['#', 'components', 'schemas', 'Address']
+ * Output: Returns 'Address'
+ */
+export declare function getRefName(ref: string): string | undefined;

package/dist/core/schema/references/get-ref-name.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRefName = getRefName;
+/**
+ * Extracts the type name from an OpenAPI schema reference ($ref)
+ *
+ * @function getRefName
+ * @param ref - OpenAPI schema reference path (e.g., '#/components/schemas/Address')
+ * @returns The referenced type name, or undefined if the reference is invalid
+ *
+ * @example
+ * // Basic usage with Address schema
+ * getRefName('#/components/schemas/Address')
+ * // Returns: 'Address'
+ *
+ * // Nested Address schema
+ * getRefName('#/components/schemas/Location/Address')
+ * // Returns: 'Address'
+ *
+ * // Complex Address reference
+ * getRefName('#/components/schemas/Shipping/Address/Details')
+ * // Returns: 'Details'
+ *
+ * // Invalid path
+ * getRefName('')
+ * // Returns: undefined
+ *
+ * @note
+ * - Expects standard OpenAPI reference paths (e.g., '#/components/schemas/Address')
+ * - Extracts the last segment of the path as the type name
+ * - Returns undefined for empty strings or invalid paths
+ * - Used when processing Address and other schema references in OpenAPI
+ *
+ * @description
+ * Processes OpenAPI $ref strings to extract schema type names.
+ * For example, when processing an Address schema reference:
+ * Input: '#/components/schemas/Address'
+ * Process: Splits by '/' -> ['#', 'components', 'schemas', 'Address']
+ * Output: Returns 'Address'
+ */
+function getRefName(ref) {
+    // split('/'): Split a string into an array using slashes
+    // 1. ["#", "components", "schemas", "Address"]
+    // pop() to get the last element
+    // 2. "Address"
+    return ref.split('/').pop();
+}

package/dist/core/schema/references/resolve-schema-order.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolves the order of schema processing based on their dependencies using depth-first search
+ *
+ * @function resolveSchemaOrder
+ * @param name - The name of the current schema to process
+ * @param dependencies - Map of schema names to their dependent schema names
+ * @param visited - Set of schema names that have been processed
+ * @param ordered - Array to store the resolved order of schema names
+ * @returns void
+ *
+ * @example
+ * const dependencies = new Map([
+ *   ['User', new Set(['Address'])],
+ *   ['Address', new Set(['Country'])],
+ *   ['Country', new Set()]
+ * ])
+ *
+ * const visited = new Set<string>()
+ * const ordered: string[] = []
+ *
+ * resolveSchemaOrder('User', dependencies, visited, ordered)
+ * // ordered will be: ['Country', 'Address', 'User']
+ *
+ * @note
+ * - Uses depth-first search to resolve dependencies
+ * - Prevents circular references by tracking visited schemas
+ * - Ensures dependent schemas appear before schemas that depend on them
+ * - Modifies the ordered array in-place to build the final sequence
+ */
+export declare function resolveSchemaOrder(name: string, dependencies: Map<string, Set<string>>, visited: Set<string>, ordered: string[]): void;