@ojiepermana/angular-sdk 22.0.36 → 22.0.41

package/README.md

@@ -1,97 +1,51 @@
-# SDK Generator
+# @ojiepermana/angular-sdk
 
-OpenAPI → Angular SDK generator shipped as the secondary entrypoint
-`@ojiepermana/angular/generator/api`.
+OpenAPI 3.x → Angular SDK generator for the `@ojiepermana/angular` design system.
+Source lives in [`library/sdk`](.); the package publishes as `@ojiepermana/angular-sdk`
+and is also re-exported as the umbrella secondary entry point `@ojiepermana/angular/sdk`.
 
-It generates a **lightweight Angular SDK** from any OpenAPI 3.x spec (including
-3.2.0): typed `HttpClient` services, tree-shakeable fn modules, optional
-metadata (permissions / validators), and a navigation tree.
+It generates a **lightweight Angular SDK** from any OpenAPI 3.x spec (including 3.2.0):
+typed `HttpClient` services, tree-shakeable fn modules, optional metadata
+(permissions / validators), and a navigation tree.
 
-## Local development in this repo
+## What the published package exposes
 
-```bash
-# 1. Build the schematic runtime
-bun run gen:sdk:build
+The npm artifact currently ships the **typed config surface** — the contract you author
+your `sdk.config.json` against — from [`public-api.ts`](public-api.ts):
 
-# 2. Scaffold a workspace config
-bun run gen:sdk:init
-
-# 3. Edit sdk.config.json, then generate
-bun run gen:sdk
-
-# 4. Run the split-by-domain regression checks
-bun run test:gen:sdk
-```
-
-## Consumer usage after publish
-
-```bash
-# inside an Angular workspace that installed @ojiepermana/angular
-ng generate @ojiepermana/angular:sdk-init
-# edit config/sdk.config.json
-ng generate @ojiepermana/angular:sdk
-```
-
-The main consumer feature is generating an SDK from
-`config/sdk.config.json`. The consumer flow is: initialize the config once,
-edit it, then run `sdk` whenever the OpenAPI source changes.
-
-If a consumer wants short script aliases in `package.json`, they can add this
-script block to their workspace:
-
-```json
-{
-  "scripts": {
-    "gen:sdk:init": "ng generate @ojiepermana/angular:sdk-init",
-    "gen:sdk": "ng generate @ojiepermana/angular:sdk"
-  }
-}
-```
-
-Consumers do not need a `gen:sdk:build` step. That build command only exists
-for developing this repository, where the schematic source under
-`projects/angular/generator/api` must be compiled before local execution.
-
-## Schematics
-
-The entrypoint exposes two schematics, registered in the parent collection at [`projects/angular/collection.json`](../../collection.json):
-
-| Schematic  | Script                 | Purpose                                          |
-| ---------- | ---------------------- | ------------------------------------------------ |
-| `sdk-init` | `bun run gen:sdk:init` | Create `config/sdk.config.json` from the example |
-| `sdk`      | `bun run gen:sdk`      | Run the generator using `config/sdk.config.json` |
-
-Both can be invoked directly with `ng generate` too:
-
-```bash
-bunx ng generate ./projects/angular/collection.json:sdk-init [--force] [--path=custom/sdk.config.json]
-bunx ng generate ./projects/angular/collection.json:sdk      [--dry-run] [--config=sdk.config.json] [--target=1]
-
-# after publish / inside a consuming workspace:
-ng generate @ojiepermana/angular:sdk-init [--force] [--path=custom/sdk.config.json]
-ng generate @ojiepermana/angular:sdk      [--dry-run] [--config=sdk.config.json] [--target=1]
+```ts
+import {
+  resolveConfig,
+  resolveTarget,
+  type SdkConfig,
+  type SdkTargetConfig,
+  type SdkOutputMode,
+  type SdkFeatureFlags,
+} from '@ojiepermana/angular-sdk';
 ```
 
-### `init` options
-
-| Option    | Type    | Default                  | Description                                   |
-| --------- | ------- | ------------------------ | --------------------------------------------- |
-| `--path`  | string  | `config/sdk.config.json` | Destination path, relative to workspace root. |
-| `--force` | boolean | `false`                  | Overwrite the file if it already exists.      |
-
-### `sdk` options
-
-| Option      | Type   | Default                  | Description                                                        |
-| ----------- | ------ | ------------------------ | ------------------------------------------------------------------ |
-| `--config`  | string | `config/sdk.config.json` | Path to the config file, relative to workspace root.               |
-| `--target`  | string | _(all)_                  | Only generate one target. Accepts a 1-based index or `clientName`. |
-| `--dry-run` | flag   | —                        | Preview file operations without writing anything.                  |
+The generator implementation itself lives in the source tree:
+
+| Path                 | Role                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| `src/config/`        | Config schema + loader (JSONC, `.js`/`.cjs`) — `resolveConfig` / `resolveTarget`                 |
+| `src/parser/`        | OpenAPI → intermediate representation (`bundle`, `ir`, `types`)                                  |
+| `src/emit/`          | One emitter per concern (models, operations, services, client, metadata, navigation, public-api) |
+| `src/layout/`        | Post-emit transforms (e.g. `per-domain` split-by-domain reorganisation)                          |
+| `src/render/`        | Template rendering                                                                               |
+| `src/writer/`        | Output-mode wrappers (standalone / library / secondary-entrypoint)                               |
+| `src/engine.ts`      | `generate(target, workspaceRoot)` — runs the full pipeline for one target                        |
+| `schematics/init/`   | Scaffolds `config/sdk.config.json` from [`sdk.config.example.json`](sdk.config.example.json)     |
+| `schematics/sdk/`    | Runs the generator and writes files into the Angular CLI `Tree`                                  |
+| `schematics/ng-add/` | `ng add` support — installs peer deps                                                            |
+| `bin/`               | Compiled JS output of `src/` + `schematics/` (via `tsconfig.schematics.json`)                    |
 
 ## Config shape
 
+A single config file drives one or more generation targets:
+
 ```jsonc
 {
-  "$schema": "./node_modules/@ojiepermana/angular/generator/api/schematics/sdk/schema.json",
   "targets": [
     {
       "input": "./openapi.yaml",
@@ -116,11 +70,12 @@ ng generate @ojiepermana/angular:sdk      [--dry-run] [--config=sdk.config.json]
 }
 ```
 
-Multiple targets are supported — one config run can emit several SDKs.
+Multiple targets are supported — one config run can emit several SDKs. See
+[`sdk.config.example.json`](sdk.config.example.json) for the canonical template the
+`init` schematic scaffolds.
 
-If `rootUrl` is omitted or left empty, the generated SDK uses same-origin
-requests by default. Consumer apps can override it at runtime with
-`provideApiConfiguration(...)`.
+If `rootUrl` is omitted or left empty, the generated SDK uses same-origin requests by
+default. Consumer apps can override it at runtime with `provideApiConfiguration(...)`.
 
 ### Runtime base URL
 
@@ -135,8 +90,6 @@ The generated SDK does not read `sdk.config.json` at runtime. The value of
 - Runtime override: consumer apps can replace the default by providing a new
   value during bootstrap.
 
-Example runtime override in a consumer app:
-
 ```ts
 import { bootstrapApplication } from '@angular/platform-browser';
 import { provideHttpClient } from '@angular/common/http';
@@ -150,8 +103,18 @@ bootstrapApplication(AppComponent, {
 ```
 
 For standalone generated output inside the same workspace, import
-`provideApiConfiguration` from the generated SDK barrel instead of an npm
-package path.
+`provideApiConfiguration` from the generated SDK barrel instead of an npm package path.
+
+## Output modes
+
+| Mode                   | What it emits                                                                                                                                                      | Use when…                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `standalone`           | A plain folder (no `ng-package.json`).                                                                                                                             | You consume the SDK via path alias / `tsconfig.paths` inside the same app.             |
+| `library`              | Split-by-domain output plus package metadata and nested `ng-package.json` manifests for secondary entrypoints.                                                     | You want a buildable/publishable Angular package with efficient deep imports.          |
+| `secondary-entrypoint` | Standalone output **plus** a minimal `ng-package.json` pointing at `public-api.ts`, plus nested `ng-package.json` files for split-by-domain secondary entrypoints. | You drop the folder inside an existing library so ng-packagr picks it up as a subpath. |
+
+In `library` mode, output also includes `tsconfig.lib.json` and `tsconfig.lib.prod.json`.
+`ng-package.dest` defaults to `dist/<output-folder-name>`.
 
 ## Per-domain layout
 
@@ -162,15 +125,7 @@ secondary entrypoints immediately. You can still set `splitByDomain: false` if
 you need the older flat library shape. Cross-domain models and client primitives
 land in `shared/`.
 
-```jsonc
-{
-  "splitByDomain": true,
-  "splitDepth": "service", // or "tag"
-}
-```
-
-`splitDepth` controls granularity. It is only read when `splitByDomain` is
-`true`.
+`splitDepth` controls granularity. It is only read when `splitByDomain` is `true`.
 
 | `splitDepth` | Folder strategy                                                                                                  | Example (spec with tags `Access/Role`, `Access/Permission`, `Storage/GCS`, `Storage/S3`, `Auth`)                                         |
 | ------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
@@ -205,17 +160,6 @@ import { GCSService } from '@my-scope/sdk/storage'; // splitDepth: 'service'
 import { GCSService } from '@my-scope/sdk/storage/gcs'; // splitDepth: 'tag'
 ```
 
-## Output modes
-
-| Mode                   | What it emits                                                                                                                                                      | Use when…                                                                              |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
-| `standalone`           | A plain folder (no `ng-package.json`).                                                                                                                             | You consume the SDK via path alias / `tsconfig.paths` inside the same app.             |
-| `library`              | Split-by-domain output plus package metadata and nested `ng-package.json` manifests for secondary entrypoints.                                                     | You want a buildable/publishable Angular package with efficient deep imports.          |
-| `secondary-entrypoint` | Standalone output **plus** a minimal `ng-package.json` pointing at `public-api.ts`, plus nested `ng-package.json` files for split-by-domain secondary entrypoints. | You drop the folder inside an existing library so ng-packagr picks it up as a subpath. |
-
-In `library` mode, output also includes `tsconfig.lib.json` and `tsconfig.lib.prod.json`.
-`ng-package.dest` defaults to `dist/<output-folder-name>`.
-
 ## Feature flags
 
 All default to `true`. Turn off anything you don't need to shrink the output.
@@ -232,18 +176,9 @@ All default to `true`. Turn off anything you don't need to shrink the output.
 ## Pipeline
 
 ```text
-sdk.config.json → loader → spec (YAML/JSON) → IR → emitters → writer → Angular CLI Tree
+sdk.config.json → loader → spec (YAML/JSON) → IR → emitters → layout → writer → Angular CLI Tree
 ```
 
-- `src/config/` — config schema + loader (supports JSONC and `.js`/`.cjs`).
-- `src/parser/` — OpenAPI → intermediate representation.
-- `src/emit/` — one module per output concern (models, operations, services, client, metadata, navigation, public-api).
-- `src/layout/` — post-emit layout transforms (e.g. `splitByDomain` reorganisation).
-- `src/writer/` — mode wrappers (standalone / library / secondary entrypoint).
-- `public-api.ts` — published TypeScript entrypoint for `@ojiepermana/angular/generator/api`.
-- `schematics/init/` — creates `sdk.config.json` from the example template.
-- `schematics/sdk/` — orchestrates engine and writes virtual files into the CLI `Tree`.
-
 ## Generated runtime conventions
 
 - Tree-shakeable: `import { listUsers } from './sdk/fn/user/list-users'` pulls only one HTTP call.

package/fesm2022/ojiepermana-angular-sdk.mjs

@@ -13,6 +13,7 @@ const DEFAULT_FEATURES = {
     client: true,
     metadata: true,
     navigation: true,
+    resources: false,
 };
 function resolveTarget(raw) {
     if (!raw || typeof raw !== 'object') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ojiepermana/angular-sdk",
-  "version": "22.0.36",
+  "version": "22.0.41",
   "description": "OpenAPI 3.x → Angular SDK generator (schematics + config surface) for @ojiepermana/angular.",
   "repository": {
     "type": "git",

package/types/ojiepermana-angular-sdk.d.ts

@@ -19,6 +19,8 @@ interface SdkFeatureFlags {
     metadata?: boolean;
     /** Emit navigation tree derived from tags (parent, x-icon). Default `false`. */
     navigation?: boolean;
+    /** Emit Signal-based resource helpers using rxResource(). Default `false`. */
+    resources?: boolean;
 }
 interface SdkTargetConfig {
     /** Path to OpenAPI 3.x spec (YAML or JSON). Required. */
@@ -65,6 +67,7 @@ interface ResolvedFeatureFlags {
     client: boolean;
     metadata: boolean;
     navigation: boolean;
+    resources: boolean;
 }
 interface ResolvedSdkTarget {
     input: string;