@ojiepermana/angular 21.0.0 → 21.0.3

package/generator/api/README.md

@@ -0,0 +1,218 @@
+# SDK Generator
+
+OpenAPI → Angular SDK generator shipped as the secondary entrypoint
+`@ojiepermana/angular/generator/api`.
+
+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
+
+```bash
+# 1. Build the schematic runtime
+bun run gen:sdk:build
+
+# 2. Scaffold a workspace config
+bun run gen:sdk:init
+
+# 3. Edit sdk.config.json, then generate
+bun run gen:sdk
+```
+
+## Consumer usage after publish
+
+```bash
+# inside an Angular workspace that installed @ojiepermana/angular
+ng generate @ojiepermana/angular:sdk-init
+ng generate @ojiepermana/angular:sdk
+```
+
+## 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 `sdk.config.json` at the workspace root from the example |
+| `sdk`      | `bun run gen:sdk`      | Run the generator using `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]
+```
+
+### `init` options
+
+| Option    | Type    | Default           | Description                                   |
+| --------- | ------- | ----------------- | --------------------------------------------- |
+| `--path`  | string  | `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 | `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.                  |
+
+## Config shape
+
+```jsonc
+{
+  "$schema": "./node_modules/@ojiepermana/angular/generator/api/schematics/sdk/schema.json",
+  "targets": [
+    {
+      "input": "./openapi.yaml",
+      "output": "./sdk",
+      "mode": "standalone", // "standalone" | "library" | "secondary-entrypoint"
+      "clientName": "Api",
+      "packageName": "@my-scope/sdk", // only used in "library" mode
+      "packageVersion": "0.0.1", // only used in "library" mode
+      "rootUrl": "", // optional; empty string means same-origin requests
+      "splitByDomain": false, // optional, default false — see "Per-domain layout"
+      "splitDepth": "service", // "service" (default) | "tag"
+      "features": {
+        "models": true,
+        "operations": true,
+        "services": true,
+        "client": true,
+        "metadata": true,
+        "navigation": true,
+      },
+    },
+  ],
+}
+```
+
+Multiple targets are supported — one config run can emit several SDKs.
+
+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
+
+The generated SDK does not read `sdk.config.json` at runtime. The value of
+`targets[].rootUrl` is only used during code generation to seed the default
+`ApiConfiguration.rootUrl` value.
+
+- `rootUrl: ""` or omitted: requests use the current origin, for example
+  `/api/users` on the same host as the Angular app.
+- `rootUrl: "https://api.example.com"`: the generated SDK defaults to that
+  absolute backend URL.
+- 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';
+
+import { AppComponent } from './app/app.component';
+import { provideApiConfiguration } from '@my-scope/sdk';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideHttpClient(), provideApiConfiguration('https://api.example.com')],
+});
+```
+
+For standalone generated output inside the same workspace, import
+`provideApiConfiguration` from the generated SDK barrel instead of an npm
+package path.
+
+## Per-domain layout
+
+By default the generator emits a flat layout (`models/`, `fn/`, `services/`, …
+all at the output root). Set `splitByDomain: true` to reorganise the output
+into one folder per domain, derived from OpenAPI tags. 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` | Folder strategy                                                                                                  | Example (spec with tags `Access/Role`, `Access/Permission`, `Storage/GCS`, `Storage/S3`, `Auth`)                                         |
+| ------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `service`    | One folder per **root** tag (each tag's `parent` chain collapses to its root). One folder per backend service.   | `access/` (holds Role + Permission + Role-Permission + …), `storage/` (holds GCS + S3), `auth/`, `shared/`, root `public-api.ts`         |
+| `tag`        | One folder per **leaf** tag, nested under the parent chain. Keeps fine-grained separation while staying grouped. | `access/role/`, `access/permission/`, `access/role-permission/`, `storage/gcs/`, `storage/s3/`, `auth/`, `shared/`, root `public-api.ts` |
+
+Every domain folder contains `services/`, `fn/`, `models/`, `permissions/`,
+and its own `public-api.ts` (which re-exports `shared/public-api` for
+convenience). The root `public-api.ts` aggregates `shared` plus every domain,
+so consumers can still do `import { UserService } from './sdk'` regardless of
+layout.
+
+Model ownership rule (per-domain mode):
+
+- A model used by exactly one domain → emitted inside that domain's `models/`.
+- A model shared across two or more domains → emitted inside `shared/models/`.
+- Client primitives (`ApiConfiguration`, `BaseService`, `RequestBuilder`,
+  `StrictHttpResponse`, `Api`), metadata, validators, and the top-level
+  `permissions/index.ts` always live under `shared/`.
+
+Example consumption when using `mode: 'library'` with `splitByDomain: true`:
+
+```ts
+import { RoleService } from '@my-scope/sdk/access';
+import { ApprovalInstanceService, SubmitRequest } from '@my-scope/sdk/approval';
+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`              | Standalone output **plus** `ng-package.json`, `package.json` (peerDeps), and `README.md`. | You want to build it with ng-packagr and publish to npm.                               |
+| `secondary-entrypoint` | Standalone output **plus** a minimal `ng-package.json` pointing at `public-api.ts`.       | You drop the folder inside an existing library so ng-packagr picks it up as a subpath. |
+
+## Feature flags
+
+All default to `true`. Turn off anything you don't need to shrink the output.
+
+| Flag         | Emits                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `models`     | `models/*.ts` — flat interfaces, enum aliases, array aliases.                              |
+| `operations` | `fn/<tag>/<operation-id>.ts` — tree-shakeable request functions with `.PATH`.              |
+| `services`   | `services/<tag>.service.ts` — `@Injectable({providedIn:'root'})` wrappers.                 |
+| `client`     | `api-configuration.ts`, `base-service.ts`, `request-builder.ts`, `api.ts`.                 |
+| `metadata`   | `permissions/*`, `validators/*`, `metadata.ts`, `openapi-helpers.ts`.                      |
+| `navigation` | `api.navigation.ts` — `NavigationItem[]` ready for `NavigationService.registerItems(...)`. |
+
+## Pipeline
+
+```
+sdk.config.json → loader → spec (YAML/JSON) → IR → emitters → 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.
+- Services: every operation gets `op()` (body `Observable<T>`) and `op$Response()` (full `StrictHttpResponse<T>`).
+- `RequestBuilder` is intentionally minimal — no `style`/`explode` logic — to keep the output lightweight.
+- All files carry a `DO NOT EDIT` banner and `/* eslint-disable */`.

package/generator/api/bin/schematics/init/index.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Default config template. The published package also ships a concrete
+ * `sdk.config.example.json`; this fallback only exists so `init` still works if
+ * the file is missing in unusual local/dev states.
+ */
+const FALLBACK_TEMPLATE = {
+    $schema: './node_modules/@ojiepermana/angular/generator/api/schematics/sdk/schema.json',
+    targets: [
+        {
+            input: './openapi.yaml',
+            output: './sdk',
+            mode: 'standalone',
+            clientName: 'Api',
+            rootUrl: '',
+            splitByDomain: false,
+            splitDepth: 'service',
+            features: {
+                models: true,
+                operations: true,
+                services: true,
+                client: true,
+                metadata: true,
+                navigation: true,
+            },
+        },
+    ],
+};
+function init(options = {}) {
+    return (tree, context) => {
+        const workspaceRoot = process.cwd();
+        const destRelative = options.path ?? 'config/sdk.config.json';
+        const treePath = destRelative.startsWith('/') ? destRelative : `/${destRelative}`;
+        if (tree.exists(treePath) && !options.force) {
+            throw new Error(`${destRelative} already exists. Re-run with --force to overwrite.`);
+        }
+        const content = loadTemplate(workspaceRoot, destRelative);
+        const buffer = Buffer.from(content, 'utf8');
+        if (tree.exists(treePath)) {
+            tree.overwrite(treePath, buffer);
+            context.logger.info(`[sdk:init] overwrote ${destRelative}`);
+        }
+        else {
+            tree.create(treePath, buffer);
+            context.logger.info(`[sdk:init] created ${destRelative}`);
+        }
+        context.logger.info(`[sdk:init] edit targets[].input and targets[].output, then run \`${getNextCommand(workspaceRoot)}\`.`);
+    };
+}
+function loadTemplate(workspaceRoot, destRelative) {
+    const candidates = [
+        (0, node_path_1.resolve)(workspaceRoot, 'sdk.config.example.json'),
+        (0, node_path_1.resolve)(__dirname, '../../../sdk.config.example.json'),
+        (0, node_path_1.resolve)(workspaceRoot, 'projects/angular/generator/api/sdk.config.example.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(candidate, 'utf8'));
+            parsed.$schema = resolveSchemaPath(workspaceRoot, destRelative);
+            return `${JSON.stringify(parsed, null, 2)}\n`;
+        }
+        catch {
+            // try next
+        }
+    }
+    return `${JSON.stringify({ ...FALLBACK_TEMPLATE, $schema: resolveSchemaPath(workspaceRoot, destRelative) }, null, 2)}\n`;
+}
+function resolveSchemaPath(workspaceRoot, destRelative) {
+    const prefix = relativePrefix(destRelative);
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(workspaceRoot, 'projects/angular/generator/api/schematics/sdk/schema.json'))) {
+        return `${prefix}projects/angular/generator/api/schematics/sdk/schema.json`;
+    }
+    return `${prefix}node_modules/@ojiepermana/angular/generator/api/schematics/sdk/schema.json`;
+}
+function relativePrefix(destRelative) {
+    const depth = destRelative.replace(/^\/+/, '').split('/').length - 1;
+    return depth <= 0 ? './' : '../'.repeat(depth);
+}
+function getNextCommand(workspaceRoot) {
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(workspaceRoot, 'projects/angular/collection.json'))) {
+        return 'bun run gen:sdk';
+    }
+    return 'ng generate @ojiepermana/angular:sdk';
+}

package/generator/api/bin/schematics/sdk/index.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sdk = sdk;
+const node_path_1 = require("node:path");
+const loader_1 = require("../../src/config/loader");
+const engine_1 = require("../../src/engine");
+/**
+ * Schematic factory. Reads `sdk.config.json` at the workspace root, runs the
+ * pure generator, and writes each emitted file into the Tree so
+ * `--dry-run` / `--force` behave as expected.
+ */
+function sdk(options = {}) {
+    return async (tree, context) => {
+        const workspaceRoot = process.cwd();
+        const configPath = options.config ?? 'config/sdk.config.json';
+        const targets = (0, loader_1.loadConfig)(configPath, workspaceRoot);
+        const selected = selectTargets(targets, options.target);
+        if (selected.length === 0) {
+            throw new Error(`No SDK targets matched "${options.target}"`);
+        }
+        for (const target of selected) {
+            const result = await (0, engine_1.generate)(target, workspaceRoot);
+            writeResult(tree, workspaceRoot, result, context);
+        }
+    };
+}
+function selectTargets(targets, selector) {
+    if (!selector)
+        return [...targets];
+    const idx = Number.parseInt(selector, 10);
+    if (!Number.isNaN(idx) && idx > 0 && idx <= targets.length) {
+        return [targets[idx - 1]];
+    }
+    const lc = selector.toLowerCase();
+    return targets.filter((t) => t.clientName.toLowerCase() === lc || t.output.toLowerCase().includes(lc) || t.packageName.toLowerCase() === lc);
+}
+function writeResult(tree, workspaceRoot, result, context) {
+    const relOutput = (0, node_path_1.relative)(workspaceRoot, result.outputDir) || '.';
+    context.logger.info(`[sdk] ${result.target.mode} → ${relOutput} ` +
+        `(schemas=${result.stats.schemas}, operations=${result.stats.operations}, ` +
+        `tags=${result.stats.tags}, files=${result.stats.files})`);
+    for (const file of result.files) {
+        const absolute = (0, node_path_1.resolve)(result.outputDir, file.path);
+        const treePath = normalizeTreePath(workspaceRoot, absolute);
+        const buffer = Buffer.from(file.content, 'utf8');
+        if (tree.exists(treePath)) {
+            tree.overwrite(treePath, buffer);
+        }
+        else {
+            tree.create(treePath, buffer);
+        }
+    }
+}
+function normalizeTreePath(workspaceRoot, absolute) {
+    const rel = (0, node_path_1.relative)(workspaceRoot, absolute);
+    const posix = rel.split(/\\+/).join('/');
+    return posix.startsWith('/') ? posix : `/${posix}`;
+}

package/generator/api/bin/src/config/loader.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const schema_1 = require("./schema");
+/**
+ * Loads an SDK generator config from disk. Supports `.json` and `.js`/`.cjs`
+ * (require-based). `.ts` is intentionally not supported in the first iteration
+ * to avoid pulling an extra compile step — use `.json` or `.js` instead.
+ */
+function loadConfig(configPath, workspaceRoot) {
+    const absolute = (0, node_path_1.isAbsolute)(configPath) ? configPath : (0, node_path_1.resolve)(workspaceRoot, configPath);
+    if (!(0, node_fs_1.existsSync)(absolute)) {
+        throw new Error(`SDK config not found at ${absolute}`);
+    }
+    const ext = (0, node_path_1.extname)(absolute).toLowerCase();
+    let raw;
+    if (ext === '.json' || ext === '') {
+        const text = (0, node_fs_1.readFileSync)(absolute, 'utf8');
+        raw = JSON.parse(stripJsonComments(text));
+    }
+    else if (ext === '.js' || ext === '.cjs') {
+        const mod = require(absolute);
+        raw = extractDefaultExport(mod);
+    }
+    else {
+        throw new Error(`Unsupported SDK config extension: ${ext} (use .json or .js)`);
+    }
+    return (0, schema_1.resolveConfig)(raw);
+}
+function extractDefaultExport(mod) {
+    if (mod && typeof mod === 'object' && 'default' in mod) {
+        return mod.default;
+    }
+    return mod;
+}
+function stripJsonComments(text) {
+    // Minimal JSONC support: strip // line comments and /* */ block comments.
+    return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+}

package/generator/api/bin/src/config/schema.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Public config shape for the SDK generator.
+ *
+ * Users place an `sdk.config.json` at the workspace root describing one or more
+ * generation targets. All paths are resolved relative to the workspace root
+ * (i.e. the directory containing the config file).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTarget = resolveTarget;
+exports.resolveConfig = resolveConfig;
+const DEFAULT_BANNER = '/* eslint-disable */\n/* Auto-generated by @ojiepermana/angular/generator/api. DO NOT EDIT. */';
+const DEFAULT_FEATURES = {
+    models: true,
+    operations: true,
+    services: true,
+    client: true,
+    metadata: true,
+    navigation: true,
+};
+function resolveTarget(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('Invalid target: expected object');
+    }
+    if (!raw.input)
+        throw new Error('Target is missing required "input"');
+    if (!raw.output)
+        throw new Error('Target is missing required "output"');
+    const mode = raw.mode ?? 'standalone';
+    if (!['standalone', 'library', 'secondary-entrypoint'].includes(mode)) {
+        throw new Error(`Invalid target mode: ${mode}`);
+    }
+    return {
+        input: raw.input,
+        output: raw.output,
+        mode,
+        clientName: raw.clientName ?? 'Api',
+        packageName: raw.packageName ?? '@local/sdk',
+        packageVersion: raw.packageVersion ?? '0.0.1',
+        rootUrl: raw.rootUrl,
+        features: { ...DEFAULT_FEATURES, ...(raw.features ?? {}) },
+        splitByDomain: raw.splitByDomain === true,
+        splitDepth: raw.splitDepth === 'tag' ? 'tag' : 'service',
+        banner: raw.banner ?? DEFAULT_BANNER,
+    };
+}
+function resolveConfig(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('Invalid SDK config: root must be an object');
+    }
+    const cfg = raw;
+    if (!Array.isArray(cfg.targets) || cfg.targets.length === 0) {
+        throw new Error('Invalid SDK config: "targets" must be a non-empty array');
+    }
+    return cfg.targets.map(resolveTarget);
+}