@accelbyte/codegen 4.1.6 → 4.2.0

package/README.md

@@ -2,24 +2,28 @@
 
 AccelByte Code Generator is a CLI tool that facilitates creating an AccelByte TypeScript SDK from AccelByte OpenAPI definitions.
 
+## Requirements
+
+- **Node.js >= 22.18.0** (LTS) — required for native TypeScript type stripping, used to load `abcodegen.config.ts` at runtime.
+
 ## CLI
 This codegen build a CLI called `accelbyte-codegen` that will be used to generate code from given config.
 
 ```
-Commands:  
-accelbyte-codegen download-swaggers  Download swaggers JSON files  
-accelbyte-codegen generate-code      Generate code based on downloaded swagger files
+Commands:
+accelbyte-codegen download-swaggers  Download swagger JSON files
+accelbyte-codegen generate-code      Generate code from downloaded swagger files
 
 Options:
---version           Show version number                                                               [boolean]  
---config            Path to the config file with backend service URLs.                                [string] [required]  
---swaggersOutput    Directory to save the downloaded Swagger JSON files.                              [string] [required]  
---output            Directory for the generated code. Required when using the generate-code command.  [string]  
---help              Show help                                                                         [boolean]
---skipReactQuery    Disable React Query code generation.                                              [boolean]
---snippetOutput     Generate only code snippets.                                                      [boolean]
---snippetOnly       Directory for the generated code snippets. Required when generating snippets.     [boolean]
---webSocketSchema   Path to the WebSocket schema file (schema.json).                                  [string]
+--version                   Show version number                                                     [boolean]
+--config                    Path to the config file with backend service URLs.                      [string] [required]
+--swaggersOutput            Directory to save the downloaded Swagger JSON files.                    [string] [required]
+--output                    Directory for the generated code. Required for generate-code.           [string]
+--help                      Show help                                                               [boolean]
+--skipReactQuery            Disable React Query code generation.                                    [boolean]
+--snippetOnly               Generate only code snippets.                                            [boolean]
+--snippetOutput             Directory for the generated code snippets.                              [string]
+--webSocketSchema           Path to the WebSocket schema file (schema.json).                        [string]
 ```
 
 ### Config file
@@ -33,9 +37,11 @@ Provide swaggers url you wish to generate, store it in .json format file.
 
 ## How to Generate
 
-**Step 1: Set Up Your Node.js Environment** Make sure you have Node.js and npm (Node Package Manager) installed on your system. You can download and install them from the official website: https://nodejs.org/en/ 
+**Step 1: Set Up Your Node.js Environment** Make sure you have **Node.js >= 22.18.0** (LTS) and npm (Node Package Manager) installed on your system. You can download and install them from the official website: https://nodejs.org/en/
+
+This minimum version is required because the codegen loads `abcodegen.config.ts` at runtime using Node.js native TypeScript type stripping, which was unflagged in Node.js 22.18.0.
 
-__*It is recommended__ to use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install Node.js so you can switch between Node versions more easily 
+__*It is recommended__ to use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install Node.js so you can switch between Node versions more easily
 
 **Step 2: Create a New Node.js Project (if needed)** If you are starting a new project, create a new directory and initialize it as a Node.js project. You can do this using the following commands: 
 ```
@@ -110,4 +116,95 @@ after installing, execute prettier as below
 npm exec prettier --write swaggers/*.json && prettier --write sdk/**/*
 # Or, with yarn:
 yarn prettier --write swaggers/*.json && prettier --write sdk/**/*
-```
+```
+
+## Configuration
+
+Place an `abcodegen.config.ts` file next to your `swaggers.json` to customize codegen behavior. All options are optional — if the file is absent, defaults apply.
+
+```typescript
+// abcodegen.config.ts
+import { type CodegenConfigOptions } from '@accelbyte/codegen'
+
+export default {
+  // Override the base path prepended to all API routes.
+  // Default: uses basePath from the swagger spec.
+  basePath: '/custom',
+
+  // Generate barrel index files (index.ts, all-imports.ts, all-query-imports.ts).
+  // Default: true
+  shouldProduceIndexFiles: false,
+
+  // Force specific definitions to emit `z.any()` instead of a full schema.
+  // Keyed by definition file name. Value can be `true` or a function receiving the schema.
+  overrideAsAny: {
+    ProtobufAny: true,
+    SomeOther: (schema) => schema.properties?.['@type'] !== undefined
+  },
+
+  // Output each swagger set into a subfolder named after its service name.
+  // Default: false
+  unstable_splitOutputByServiceName: true
+} satisfies CodegenConfigOptions
+```
+
+### `unstable_splitOutputByServiceName`
+
+By default, all swagger sets in `swaggers.json` are generated into the same `--output` directory. When this option is enabled, each set is placed in a subfolder named after its service name (the first element of each inner array).
+
+Given a config like:
+
+```json
+[
+  ["iam",      "iam",      "iam.json",      "https://example.com/iam/apidocs/api.json"],
+  ["platform", "platform", "platform.json", "https://example.com/platform/swagger.json"]
+]
+```
+
+The output becomes:
+
+```
+sdk/
+  iam/
+    generated-admin/
+    generated-public/
+    generated-definitions/
+    Iam.ts
+  platform/
+    generated-admin/
+    generated-public/
+    generated-definitions/
+    Platform.ts
+  all-imports.ts        ← re-exports from all subfolders
+  all-query-imports.ts
+```
+
+Enable via `abcodegen.config.ts`:
+
+```typescript
+export default {
+  unstable_splitOutputByServiceName: true
+} satisfies CodegenConfigOptions
+```
+
+## Design Decisions
+
+### Zod definitions use `interface`, not `type`
+
+Generated definitions use `interface Foo extends z.TypeOf<typeof Foo> {}` rather than a `type` alias. This makes editors display the object shape directly on hover instead of showing the `z.TypeOf<...>` indirection.
+
+This triggers `@typescript-eslint/no-empty-object-type`. That rule guards against the `{}` gotcha in hand-written code, which does not apply to generated output. Consumers can disable it for generated files:
+
+```js
+// eslint.config.js
+{
+  files: ['src/generated-definitions/**'],
+  rules: { '@typescript-eslint/no-empty-object-type': 'off' }
+}
+```
+
+## Troubleshooting
+
+### Type or lint errors in generated files
+
+The generated code aims to use neutral, unopinionated style defaults. However, some generated syntax may conflict with your tsconfig or linter settings. In that case, you can ignore specific lint rules in the codegen folder, or create a `tsconfig.json` inside it to override your top-level configuration.

package/dist/accelbyte-codegen.d.mts

@@ -0,0 +1,31 @@
+interface CodegenConfigOptions {
+    /**
+     * Force specific definitions to emit `z.any()` instead of a full schema.
+     * Keyed by definition file name. Value can be `true` or a function receiving the schema.
+     *
+     * @example
+     * { ProtobufAny: true, SomeOther: (schema) => schema.properties?.['@type'] !== undefined }
+     */
+    overrideAsAny?: Record<string, boolean | ((schema: Record<string, any>) => boolean)>;
+    /**
+     * Generate barrel index files (index.ts, all-imports.ts, all-query-imports.ts).
+     * @default true
+     */
+    shouldProduceIndexFiles?: boolean;
+    /**
+     * Override the base path prepended to all API routes.
+     * @default `basePath` from the swagger spec
+     */
+    basePath?: string;
+    /**
+     * When enabled, each swagger set is generated into a subfolder named after its service name
+     * inside the output directory, instead of all sets sharing the same root output folder.
+     *
+     * If swaggers.json contains [["a", "b", "c", "d"]], then the service name is the "a".
+     *
+     * @default false
+     */
+    unstable_splitOutputByServiceName?: boolean;
+}
+
+export type { CodegenConfigOptions };

package/dist/accelbyte-codegen.d.ts

@@ -0,0 +1,31 @@
+interface CodegenConfigOptions {
+    /**
+     * Force specific definitions to emit `z.any()` instead of a full schema.
+     * Keyed by definition file name. Value can be `true` or a function receiving the schema.
+     *
+     * @example
+     * { ProtobufAny: true, SomeOther: (schema) => schema.properties?.['@type'] !== undefined }
+     */
+    overrideAsAny?: Record<string, boolean | ((schema: Record<string, any>) => boolean)>;
+    /**
+     * Generate barrel index files (index.ts, all-imports.ts, all-query-imports.ts).
+     * @default true
+     */
+    shouldProduceIndexFiles?: boolean;
+    /**
+     * Override the base path prepended to all API routes.
+     * @default `basePath` from the swagger spec
+     */
+    basePath?: string;
+    /**
+     * When enabled, each swagger set is generated into a subfolder named after its service name
+     * inside the output directory, instead of all sets sharing the same root output folder.
+     *
+     * If swaggers.json contains [["a", "b", "c", "d"]], then the service name is the "a".
+     *
+     * @default false
+     */
+    unstable_splitOutputByServiceName?: boolean;
+}
+
+export type { CodegenConfigOptions };