micro-contracts 0.20.0 → 0.20.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +111 -9
  2. package/cli-contract.yaml +10 -1
  3. package/dist/cli/templates.d.ts +4 -0
  4. package/dist/cli/templates.d.ts.map +1 -1
  5. package/dist/cli/templates.js +497 -48
  6. package/dist/cli/templates.js.map +1 -1
  7. package/dist/cli.js +16 -17
  8. package/dist/cli.js.map +1 -1
  9. package/dist/generated/contract.d.ts.map +1 -1
  10. package/dist/generated/contract.js +2 -2
  11. package/dist/generated/contract.js.map +1 -1
  12. package/dist/generated/policy.d.ts +6 -0
  13. package/dist/generated/policy.d.ts.map +1 -1
  14. package/dist/generated/policy.js +7 -0
  15. package/dist/generated/policy.js.map +1 -1
  16. package/dist/generated/program.d.ts +1 -0
  17. package/dist/generated/program.d.ts.map +1 -1
  18. package/dist/generated/program.js +1 -0
  19. package/dist/generated/program.js.map +1 -1
  20. package/dist/generated/types.d.ts +1 -0
  21. package/dist/generated/types.d.ts.map +1 -1
  22. package/dist/generator/index.js +149 -2
  23. package/dist/generator/index.js.map +1 -1
  24. package/dist/generator/linter.d.ts.map +1 -1
  25. package/dist/generator/linter.js +11 -6
  26. package/dist/generator/linter.js.map +1 -1
  27. package/dist/generator/serviceGenerator.d.ts +6 -0
  28. package/dist/generator/serviceGenerator.d.ts.map +1 -1
  29. package/dist/generator/serviceGenerator.js +9 -7
  30. package/dist/generator/serviceGenerator.js.map +1 -1
  31. package/dist/generator/templateProcessor.d.ts +17 -2
  32. package/dist/generator/templateProcessor.d.ts.map +1 -1
  33. package/dist/generator/templateProcessor.js +16 -3
  34. package/dist/generator/templateProcessor.js.map +1 -1
  35. package/dist/generator/typeGenerator.d.ts +3 -1
  36. package/dist/generator/typeGenerator.d.ts.map +1 -1
  37. package/dist/generator/typeGenerator.js +12 -10
  38. package/dist/generator/typeGenerator.js.map +1 -1
  39. package/dist/micro-contracts.bundle.mjs +1028 -457
  40. package/dist/micro-contracts.bundle.mjs.map +3 -3
  41. package/dist/types.d.ts +31 -10
  42. package/dist/types.d.ts.map +1 -1
  43. package/dist/types.js +52 -27
  44. package/dist/types.js.map +1 -1
  45. package/docs/cli-reference.md +5 -1
  46. package/package.json +1 -1
package/README.md CHANGED
@@ -172,11 +172,15 @@ project/
172
172
  │ │ ├── schemas/ # Types, validators
173
173
  │ │ ├── services/ # Service interfaces
174
174
  │ │ ├── overlays/ # Overlay handler interfaces
175
+ │ │ ├── errors/ # Error shape (ProblemDetails, ApiError)
176
+ │ │ ├── http/ # Request reading the server templates share (cookies)
177
+ │ │ ├── streams/ # Stream framing (modules with stream responses)
175
178
  │ │ └── deps/ # Re-exports from dependencies
176
179
  │ └── contract-published/{module}/ # Public API subset
177
180
  │
178
181
  ├── server/src/{module}/
179
182
  │ ├── routes.generated.ts # ❌ Auto-generated (template: fastify-routes.hbs)
183
+ │ ├── lambda.generated.ts # ❌ Auto-generated (template: lambda-routes.hbs, init --lambda)
180
184
  │ ├── services/ # ✅ Human-edited (service implementations)
181
185
  │ └── overlays/ # ✅ Human-edited (overlay implementations)
182
186
  │
@@ -299,7 +303,7 @@ Create `micro-contracts.config.yaml`. All paths support `{module}` placeholder.
299
303
  | `outputs.<id>.output` | string | yes | Output file path |
300
304
  | `outputs.<id>.template` | string | yes | Handlebars template file path, used as written (resolved from the working directory) |
301
305
  | `outputs.<id>.overwrite` | boolean | no | Overwrite existing files (default: `true`) |
302
- | `outputs.<id>.condition` | string | no | `hasPublicEndpoints` \| `hasOverlays` \| `always` (default: `always`) |
306
+ | `outputs.<id>.condition` | string | no | `hasPublicEndpoints` \| `hasOverlays` \| `always` (default: `always`). An output under `hasPublicEndpoints` is generated for a module with published operations, and rendered over what `contract-published` carries: those operations and their schemas |
303
307
  | `outputs.<id>.enabled` | boolean | no | Enable/disable this output (default: `true`) |
304
308
  | `outputs.<id>.config` | object | no | Template-specific configuration passed to context |
305
309
 
@@ -421,6 +425,7 @@ Initialize a new module structure with starter templates.
421
425
  | `-o, --output <path>` | Output path for processed OpenAPI |
422
426
  | `--skip-templates` | Skip creating starter templates |
423
427
  | `--screens` | Initialize as screen spec module (generates screen templates and starter spec) |
428
+ | `--lambda` | Also create the AWS Lambda handler template (`lambda-routes.hbs`), and configure it as the server output in place of the Fastify routes (see [AWS Lambda](#aws-lambda)) |
424
429
 
425
430
  ### lint \<input\>
426
431
 
@@ -441,12 +446,15 @@ do not apply.
441
446
  An operation's success response is its lowest 2xx status code, else its `2XX` range, else
442
447
  `default`: the service returns that response's body and the generated route answers with
443
448
  that status (200 for `2XX` and `default`). An operation that declares none of them is an
444
- error: declare the response a successful call returns. Its request body and success response
445
- must be in a media type generated code carries — `application/json` — since a body in any
446
- other media type would be dropped from every generated artifact; one declared otherwise is an
447
- error: remove that media type, and declare the body as `application/json`. A response of any
448
- other status, which documents an error, may use any media type; generated code has a schema
449
- only for an `application/json` one.
449
+ error: declare the response a successful call returns. Its request body must be
450
+ `application/json`, and its success response `application/json` or a stream —
451
+ `text/event-stream`, `application/x-ndjson` or `application/jsonl` — since a body in any other
452
+ media type would be dropped from every generated artifact; one declared otherwise is an
453
+ error: remove that media type, and declare the body in one of them. A stream declares the
454
+ schema of one event under `x-stream-event`, as a `oneOf` with `discriminator.propertyName`:
455
+ a stream without `x-stream-event`, or whose events have no discriminator, is an error. A
456
+ response of any other status, which documents an error, may use any media type; generated
457
+ code has a schema only for an `application/json` one.
450
458
 
451
459
  `<input>` is linted under the rules of the module in `micro-contracts.config.yaml` whose
452
460
  `openapi` it is — the rules `generate` applies to it — and as a service API spec when no
@@ -619,13 +627,58 @@ export class UserService implements UserServiceApi {
619
627
  }
620
628
  ```
621
629
 
630
+ ### Stream Responses
631
+
632
+ An operation whose success response is `text/event-stream` (server-sent events) or
633
+ `application/x-ndjson` / `application/jsonl` (one JSON value per line) streams events. The
634
+ schema of one event is declared under `x-stream-event`: a `oneOf` whose `discriminator`
635
+ names each event's type.
636
+
637
+ ```yaml
638
+ responses:
639
+ '200':
640
+ description: Reply, as it is written
641
+ content:
642
+ text/event-stream:
643
+ x-stream-event:
644
+ oneOf:
645
+ - $ref: '#/components/schemas/TextDelta'
646
+ - $ref: '#/components/schemas/StreamEnd'
647
+ discriminator: { propertyName: type }
648
+ ```
649
+
650
+ The event type is the referenced component, or `<Service>_<method>Event` for an inline schema,
651
+ in `schemas/types.ts` and among the validators. The service returns its events as an
652
+ `AsyncIterable`:
653
+
654
+ ```typescript
655
+ export interface ChatServiceApi {
656
+ reply(input: Chat_replyInput): AsyncIterable<Chat_replyEvent>;
657
+ }
658
+ ```
659
+
660
+ The contract package carries the framing, `streams/index.ts`: routes encode events with
661
+ `encodeStream` and clients decode them with `decodeStream`. A server-sent event is
662
+ `event: <discriminator value>`, `data: <the event as JSON>` and a blank line; NDJSON is one
663
+ event per line.
664
+
665
+ The starter Fastify route awaits the service's first event before sending anything, so a
666
+ service that fails at once answers through the error handler, as a JSON operation does. It
667
+ then sends the success status with the declared media type, and each event as the service
668
+ yields it, serialized by the event schema as a JSON response is: a property the schema does
669
+ not declare is not sent, and an event no member of the schema accepts ends the stream. When
670
+ the client goes away, the service's iterator is closed at its next yield: a service waiting
671
+ between events keeps running until it yields again. The starter fetch client returns the
672
+ events as an `AsyncIterable` to read with `for await`.
673
+
622
674
  ### Validators
623
675
 
624
676
  `schemas/validators.ts` holds every schema as the JSON Schema Fastify validates requests and
625
677
  serializes responses with, plus the path, query, header and cookie parameter schemas of each
626
678
  operation (`<Service>_<method>PathParams`, `…QueryParams`, `…HeaderParams`, `…CookieParams`)
627
- and its inline request body and response schemas (`…Body`; `…Response` for the success
628
- response, and `…404Response`, `…4XXResponse` or `…DefaultResponse` for another).
679
+ and its inline request body, response and stream event schemas (`…Body`; `…Response` for the
680
+ success response, and `…404Response`, `…4XXResponse` or `…DefaultResponse` for another;
681
+ `…Event`).
629
682
  `schemas/types.ts` names the inline body types the same way. A header parameter schema names headers in lower case, as a
630
683
  request delivers them, and is not in `allSchemas`: the starter routes give it to Fastify
631
684
  inline (`schema.headers`), since Fastify matches header names case-insensitively only in an
@@ -704,6 +757,55 @@ const fastify = Fastify();
704
757
  fastify.setValidatorCompiler(({ schema }) => ajv.compile(schema));
705
758
  ```
706
759
 
760
+ ### AWS Lambda
761
+
762
+ `init --lambda` also writes `lambda-routes.hbs`, a handler for the events of an API Gateway
763
+ HTTP API (payload format 2.0) and of a Lambda function URL, and configures it as the server
764
+ output (`server/src/{module}/lambda.generated.ts`) in place of the Fastify routes. It runs a
765
+ module's operations without Fastify — one Lambda function per module — and needs `ajv`,
766
+ `ajv-formats` and `fast-json-stringify` in your dependencies.
767
+
768
+ ```typescript
769
+ import { createHandler } from './billing/lambda.generated.js';
770
+ import { BillingService } from './billing/services/index.js';
771
+ import { requireAuth, tenantIsolation } from './billing/overlays/index.js';
772
+
773
+ export const handler = createHandler({
774
+ services: { billing: new BillingService() },
775
+ overlays: { requireAuth, tenantIsolation },
776
+ basePath: '/prod', // what the event's path carries before the spec's paths, if anything
777
+ });
778
+ ```
779
+
780
+ The handler answers as the starter Fastify routes do:
781
+
782
+ - It routes an event by `rawPath` and `requestContext.http.method`, a literal path segment
783
+ before a parameter. A path no operation has is answered with 404, and another method of an
784
+ operation's path with 405 and `Allow`.
785
+ - It validates the path, query, header and cookie parameters and the body against the
786
+ schemas the Fastify routes use, with Fastify's default validator options except
787
+ `removeAdditional: false` (see [Validators](#validators)), and words a refusal (400) as
788
+ Fastify does (`querystring/limit must be integer`). The query is read from
789
+ `rawQueryString`, a key given more than once being an array; headers in lower case; cookies
790
+ from the event's `cookies`. A body is JSON — decoded first when `isBase64Encoded` — and
791
+ another content type is answered with 415.
792
+ - It runs the operation's overlays (`overlayAdapter.generated.ts`), then the service, and
793
+ answers with the success status and the body serialized by the schema declared for it.
794
+
795
+ An error — a refused request, an overlay's refusal, a service's throw — is answered as the
796
+ contract's `ProblemDetails`, with `toProblemDetails` from the contract's `errors/`: a thrown
797
+ error's `status` or `statusCode` (400–599) is the response's status, any other error is 500
798
+ and logged, and its message is the title. The body is serialized by the schema declared for
799
+ that status, as Fastify serializes an error.
800
+
801
+ A [stream operation](#stream-responses) needs the response streaming of a function URL whose
802
+ invoke mode is `RESPONSE_STREAM`. For one, the template exports `createStreamHandler` too, a
803
+ handler wrapped in `awslambda.streamifyResponse` that sends each event as the service yields
804
+ it. When the response stream closes, the service's iterator is closed at its next yield: a
805
+ service waiting between events keeps running until it yields again. It answers the other
806
+ operations as `createHandler` does. `createHandler` answers a stream operation with all its
807
+ events at once, when the stream ends.
808
+
707
809
  ---
708
810
 
709
811
  ## Related Documentation
package/cli-contract.yaml CHANGED
@@ -3,7 +3,7 @@ cli_contracts: 0.1.0
3
3
 
4
4
  info:
5
5
  title: micro-contracts CLI
6
- version: 0.20.0
6
+ version: 0.20.1
7
7
  description: >-
8
8
  Contract-first OpenAPI toolchain for TypeScript Web/API systems.
9
9
  Generates contract packages, server routes, and frontend clients
@@ -248,6 +248,7 @@ command_sets:
248
248
  - micro-contracts init core
249
249
  - micro-contracts init core --openapi path/to/spec.yaml
250
250
  - micro-contracts init myScreens --screens
251
+ - micro-contracts init billing --lambda
251
252
  - micro-contracts init users --skip-templates
252
253
 
253
254
  arguments:
@@ -298,6 +299,14 @@ command_sets:
298
299
  type: boolean
299
300
  default: false
300
301
 
302
+ - name: lambda
303
+ description: >-
304
+ Also create the AWS Lambda handler template (lambda-routes.hbs), and configure it as
305
+ the server output in place of the Fastify routes.
306
+ schema:
307
+ type: boolean
308
+ default: false
309
+
301
310
  exits:
302
311
  '0':
303
312
  description: Module initialized successfully.
@@ -9,6 +9,10 @@
9
9
  * Get all starter templates
10
10
  */
11
11
  export declare function getStarterTemplates(): Record<string, string>;
12
+ /**
13
+ * Get the AWS Lambda starter templates (init --lambda)
14
+ */
15
+ export declare function getLambdaStarterTemplates(): Record<string, string>;
12
16
  /**
13
17
  * Get screen spec starter templates
14
18
  */
@@ -1 +1 @@
1
- {"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/cli/templates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAugBH;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ5D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKlE"}
1
+ {"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/cli/templates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAk8BH;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ5D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIlE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKlE"}