ngx-openapi-typescript 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,138 @@
+# ngx-openapi-typescript
+
+Type-safe Angular resource signals and HTTP client backed by [openapi-typescript](https://openapi-ts.dev/).
+
+This library provides two main utilities:
+
+- **`createOpenApiResource`** — a reactive factory built on Angular's `httpResource` that gives you compile-time type safety for every HTTP request and response shape defined in your OpenAPI schema.
+- **`OpenApiHttpClient`** — a typed wrapper around Angular's `HttpClient` for imperative (non-reactive) HTTP calls.
+
+Both are driven by the types generated by `openapi-typescript`, so typos in paths, wrong parameter names, or incorrect body shapes are caught at **compile time**, not at runtime.
+
+## Installation
+
+```sh
+npm install ngx-openapi-typescript openapi-typescript-helpers
+```
+
+This package is built for Angular `^21.2.0` and `^22.0.0` and expects these peer dependencies in your app:
+
+- `@angular/common ^21.2.0 || ^22.0.0`
+- `@angular/core ^21.2.0 || ^22.0.0`
+- `openapi-typescript-helpers ^0.1.0`
+
+If you want to generate types locally, also install the generator as a dev dependency:
+
+```sh
+npm install -D openapi-typescript
+```
+
+## Generating types
+
+Generate type definitions by pointing `openapi-typescript` at your OpenAPI spec:
+
+```sh
+npx openapi-typescript https://api.example.com/openapi.yaml -o src/api.types.ts
+```
+
+This creates a `paths` interface that both utilities consume.
+
+## API
+
+### `createOpenApiResource`
+
+A factory for creating reactive Angular resource signals. Must be called inside an Angular injection context (component/service field initializer or constructor).
+
+```ts
+import type { paths } from './api.types';
+import { createOpenApiResource } from 'ngx-openapi-typescript';
+
+@Component({ ... })
+export class PetListComponent {
+  private readonly api = createOpenApiResource<paths>({
+    baseUrl: 'https://api.example.com',
+  });
+
+  // Simple GET — no params required
+  protected readonly pets = this.api('/pets');
+
+  // Reactive GET with params — re-fetches when the signals read inside the lambda change
+  protected readonly petsLimited = this.api('/pets', () => ({
+    params: { query: { limit: 10 } },
+  }));
+
+  // Pass signal-driven path params — re-fetches when petId() changes
+  private readonly petId = signal(1);
+  protected readonly pet = this.api('/pets/{petId}', () => ({
+    params: { path: { petId: this.petId() } },
+  }));
+
+  // Return undefined to put the resource in Idle state (no request made)
+  private readonly enabled = signal(false);
+  protected readonly lazyPets = this.api('/pets', () =>
+    this.enabled() ? {} : undefined,
+  );
+}
+```
+
+#### Method Override
+
+The factory defaults to GET. You can pass a `method` option to use a different HTTP method,
+but Angular recommends using `httpResource` only for reads. Prefer `OpenApiHttpClient` for mutations.
+
+```ts
+// Explicit method override (not recommended for production use)
+protected readonly createResult = this.api('/pets', () => ({
+  body: { name: 'Buddy' },
+}), { method: 'post' });
+```
+
+### `OpenApiHttpClient`
+
+A base class that wraps Angular's `HttpClient` with OpenAPI types. Ideal for imperative calls, mutations, or service-layer code.
+
+```ts
+import type { paths } from './api.types';
+import { OpenApiHttpClient } from 'ngx-openapi-typescript';
+import { Injectable } from '@angular/core';
+
+@Injectable({ providedIn: 'root' })
+export class PetApiClient extends OpenApiHttpClient<paths> {
+  constructor() {
+    super({ baseUrl: 'https://api.example.com' });
+  }
+}
+```
+
+```ts
+// In a component/service
+@Component({ ... })
+export class PetDetailComponent {
+  private readonly api = inject(PetApiClient);
+
+  load(id: number) {
+    this.api
+      .get('/pets/{petId}', { params: { path: { petId: id } } })
+      .subscribe(pet => console.log(pet)); // pet is typed as Pet
+  }
+
+  create(name: string) {
+    this.api
+      .post('/pets', { body: { name } })
+      .subscribe(newPet => console.log(newPet));
+  }
+}
+```
+
+## Development
+
+```sh
+# Build the library
+ng build ngx-openapi-typescript
+
+# Run tests
+ng test ngx-openapi-typescript
+
+# Start the demo app
+ng serve demo
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-openapi-typescript",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Type-safe Angular httpResource and HttpClient backed by openapi-typescript",
   "keywords": [
     "angular",