hexok 2.1.0 → 2.1.1

package/dist/use-case.d.ts

@@ -6,7 +6,7 @@
  *
  * ```ts
  * class CreateUser extends UseCase('user.create') {
- *   constructor(private readonly users: UserRepository) { super() }
+ *   constructor(private readonly deps: { users: UserRepository }) { super() }
  *   async execute(input: { email: string }): Promise<{ id: string }> {
  *     return { id: input.email }
  *   }
@@ -65,12 +65,12 @@ type Statics<S> = Omit<S, ReservedKey>;
  *   input: z.object({ query: z.string() }),
  *   permission: 'users.read',
  * }) {
- *   constructor(private readonly users: UserRepository) { super() }
+ *   constructor(private readonly deps: { users: UserRepository }) { super() }
  *   async execute(
  *     ctx: UseCase.Ctx<typeof ApiUseCase>,
  *     input: { query: string },
  *   ): Promise<User[]> {
- *     return this.users.search(input.query)
+ *     return this.deps.users.search(input.query)
  *   }
  * }
  * ```

package/dist/use-case.js

@@ -6,7 +6,7 @@
  *
  * ```ts
  * class CreateUser extends UseCase('user.create') {
- *   constructor(private readonly users: UserRepository) { super() }
+ *   constructor(private readonly deps: { users: UserRepository }) { super() }
  *   async execute(input: { email: string }): Promise<{ id: string }> {
  *     return { id: input.email }
  *   }
@@ -63,12 +63,12 @@ const RESERVED_STATICS = new Set([
  *   input: z.object({ query: z.string() }),
  *   permission: 'users.read',
  * }) {
- *   constructor(private readonly users: UserRepository) { super() }
+ *   constructor(private readonly deps: { users: UserRepository }) { super() }
  *   async execute(
  *     ctx: UseCase.Ctx<typeof ApiUseCase>,
  *     input: { query: string },
  *   ): Promise<User[]> {
- *     return this.users.search(input.query)
+ *     return this.deps.users.search(input.query)
  *   }
  * }
  * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexok",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "TypeScript primitives for hexagonal software: Schema, Entity, UseCase, Port, Adapter, Mapper, Event, EventCatalog, EventHandler, and Errors.",
   "type": "module",
   "license": "MIT",

package/skills/hexok/SKILL.md

@@ -60,7 +60,7 @@ A blog post is an id, a title, a body, and whether it is published. The schema i
 
 Define each use case as one action, and the ports that action calls, when they are not already there.
 
-Saving a post is a port. Publishing an event is a different port. The use case receives both in its constructor and calls them from `execute`. It does not import a driver. Read [references/use-case.md](references/use-case.md) and [references/port.md](references/port.md).
+Saving a post is a port. Publishing an event is a different port. The use case receives both on a `deps` object in its constructor and calls them from `execute` through `this.deps`. Add a second argument, `config`, only when the composition root sets flags on that long-lived instance. It does not import a driver. Read [references/use-case.md](references/use-case.md) and [references/port.md](references/port.md).
 
 Use `UseCase(token)` when `execute` only needs the input. Use `UseCase.context<Ctx>()` when every call in the family carries the same extra facts, such as a trace id, the actor, or the caller IP. Share one family across the gateway's use cases.
 
@@ -74,7 +74,7 @@ When the story has no consequence beyond its own write, this step is `none`. Do
 
 ### 3.c. Event handlers
 
-When step 3.b named a side effect, implement the handler if it does not exist. The handler takes its own ports in the constructor. `handle` receives the event. Emailing subscribers loads addresses through a subscriber port and sends mail through a mail port. Read [references/event-handler.md](references/event-handler.md).
+When step 3.b named a side effect, implement the handler if it does not exist. The handler takes its own ports on a `deps` object in the constructor. `handle` receives the event. Emailing subscribers loads addresses through a subscriber port and sends mail through a mail port. Read [references/event-handler.md](references/event-handler.md).
 
 The handler does not subscribe itself. Subscription belongs to the adapter in step 4.
 
@@ -96,7 +96,7 @@ Use the HTTP library the application already depends on. Express, Hono, and Koa
 
 The route builds the call context, calls `execute`, and maps failures to the reply. A missing entity is a 404. `CodedError` code `VALIDATION` is a 400 and `data.issues` names the fields. A catalog conflict, such as an already published post, is a 409. The catalog does not contain status codes.
 
-Construct adapters, call `start`, and construct use cases in the entry point. A use case instance is long-lived. Context is an argument to `execute`, not a field set per request.
+Construct adapters, call `start`, and construct use cases in the entry point (`new PublishPost({ posts, events })`). A use case instance is long-lived. Context is an argument to `execute`, not a field set per request.
 
 ### 6. Where handlers run
 
@@ -110,6 +110,7 @@ Do not add a broker only to create a second process. Do not move the handler's w
 
 ## Conventions
 
+- A use case, an event handler, and an adapter that takes a driver receive collaborators as one `readonly` object named `deps`, including a class with a single collaborator. Keys are the collaborator names. Write the core port first in the type. Call sites may pass keys in any order. The body uses `this.deps`. Optional instance settings are a second argument, `config?`, also `readonly`. Omit `config` when there are none. New ports go on `deps`. New flags go on `config`. Do not add a third positional argument. A per-request choice stays on `execute`'s input. A value declared for a whole `UseCase.context` family stays on that factory's static spec. Entity payloads, event payloads, error-catalog factories, and port methods stay data arguments.
 - Tokens are factory arguments: `Entity('Post', PostSchema)`, `UseCase('post.publish')`, `Port('PostRepository')`, `Event('post.published', PostSchema)`, `EventCatalog('blog', { postPublished })`, `EventHandler('email.subscribers', PostPublished)`, `Errors('blog', { ... })`. A subclass does not redeclare the token.
 - `execute`, `handle`, port methods, and a mapper's `fromSource` and `toSource` are methods on the class. The compiler reports a missing one. `start`, `stop`, `parse`, and `set` already exist and may be overridden.
 - A use case throws a catalog member when the story refuses. Schema checks throw `CodedError` with code `VALIDATION`. Catch both at the gateway or the worker.

package/skills/hexok/references/adapter.md

@@ -21,7 +21,7 @@ The use case asks a `PostRepository` to save. Something has to actually keep the
 
 ## How to use it
 
-An in-memory repository is enough to walk the publish story. The API process can later substitute a database class that extends the same port. The composition root constructs the adapter, starts it, and hands it to `PublishPost`.
+An in-memory repository is enough to walk the publish story. The API process can later substitute a database class that extends the same port. The composition root constructs the adapter, starts it, and hands it to `PublishPost` on `deps`. An adapter that takes a driver or another collaborator uses that same `deps` object.
 
 ```ts
 class InMemoryPosts extends Adapter(PostRepository) {
@@ -41,7 +41,7 @@ class InMemoryPosts extends Adapter(PostRepository) {
 
 const posts = new InMemoryPosts();
 await posts.start();
-const publishPost = new PublishPost(posts, events);
+const publishPost = new PublishPost({ posts, events });
 ```
 
 Store `toProps()` (or a mapped document) and rebuild with `restore` on the way out. Call `commit()` after the write succeeds.

package/skills/hexok/references/entity.md

@@ -46,6 +46,28 @@ Read `props` for the current data. Write only through `set` or a method that cal
 
 The adapter calls `commit()` after the driver write succeeds. That is what clears `isNew` and the dirty set. The use case does not commit, and a mapper does not commit.
 
+## Closing `set`
+
+`set` stays public. The instance is an `EntityInstance`, so a private or protected `set` is a type error.
+
+When every change belongs on a method, override `set` with a `never` producer and throw. Methods call `super.set`.
+
+```ts
+class User extends Entity('User', UserSchema) {
+  override set(_producer: never): never {
+    throw new Error('User.set is closed');
+  }
+
+  changeEmail(email: string): this {
+    return super.set((draft) => {
+      draft.email = email;
+    });
+  }
+}
+```
+
+`user.set(...)` fails to typecheck. A value typed as `EntityInstance` can still name `set`. That call throws.
+
 ## API
 
 `Entity(token, schema)` returns the class you extend. `token` is a string literal.

package/skills/hexok/references/event-handler.md

@@ -19,16 +19,18 @@ The use case that publishes a post is finished once the post is saved and the ev
 ```ts
 class EmailSubscribers extends EventHandler('email.subscribers', PostPublished) {
   constructor(
-    private readonly subscribers: SubscriberDirectory,
-    private readonly mail: MailSender,
+    private readonly deps: {
+      subscribers: SubscriberDirectory;
+      mail: MailSender;
+    },
   ) {
     super();
   }
 
   async handle(event: PostPublished): Promise<void> {
-    const addresses = await this.subscribers.list();
+    const addresses = await this.deps.subscribers.list();
     for (const address of addresses) {
-      await this.mail.send(address, event.payload.title);
+      await this.deps.mail.send(address, event.payload.title);
     }
   }
 }
@@ -51,6 +53,6 @@ A static field such as `groupId` is yours to read when you subscribe the handler
 | `EmailSubscribers.token` | The name you passed in. |
 | `EmailSubscribers.event` | The event class this handler receives. |
 | `handle(event)` | Required. Annotate `event` with that class. Return `void` or `Promise<void>`. |
-| `constructor` | Receive ports here and call `super()`. |
+| `constructor` | Ports arrive on `deps`. Call `super()`. The composition root passes `new EmailSubscribers({ subscribers, mail })`. |
 
 The compiler reports a missing `handle`. The factory records the token and the event class. It takes no consumer-group argument.

package/skills/hexok/references/mapper.md

@@ -35,12 +35,12 @@ The domain port stays in domain types. Each adapter has its own stored shape. On
 
 ```ts
 class MongoUsers extends Adapter(UserRepository) {
-  constructor(private readonly users: MongoUser) {
+  constructor(private readonly deps: { users: MongoUser }) {
     super();
   }
 
   override async save(user: User): Promise<void> {
-    const doc = this.users.toModel(user);
+    const doc = this.deps.users.toModel(user);
     await this.collection.updateOne({ _id: doc._id }, { $set: doc }, { upsert: true });
     user.commit();
   }
@@ -48,7 +48,7 @@ class MongoUsers extends Adapter(UserRepository) {
   override async get(id: string): Promise<User | null> {
     const doc = await this.collection.findOne({ _id: id });
     if (doc === null) return null;
-    return this.users.fromModel(doc);
+    return this.deps.users.fromModel(doc);
   }
 }
 ```

package/skills/hexok/references/port.md

@@ -24,23 +24,25 @@ abstract class BlogEventPublisher extends Port('BlogEventPublisher') {
 
 class PublishPost extends UseCase('post.publish') {
   constructor(
-    private readonly posts: PostRepository,
-    private readonly events: BlogEventPublisher,
+    private readonly deps: {
+      posts: PostRepository;
+      events: BlogEventPublisher;
+    },
   ) {
     super();
   }
 
   async execute(input: { id: string }): Promise<{ id: string }> {
-    const post = await this.posts.get(input.id);
+    const post = await this.deps.posts.get(input.id);
     post.publish(new Date());
-    await this.posts.save(post);
-    await this.events.publish(new PostPublished(post.toProps()));
+    await this.deps.posts.save(post);
+    await this.deps.events.publish(new PostPublished(post.toProps()));
     return { id: post.props.id };
   }
 }
 ```
 
-The methods are whatever this seam needs. A repository offers `get` and `save`. A publisher offers `publish`. A mail port offers `send`. A subscription port offers `subscribe`. Keep publishing and subscribing as two ports. `start` and `stop` stay on the adapter. The use case depends on the port class, and the composition root passes an adapter.
+The methods are whatever this seam needs. A repository offers `get` and `save`. A publisher offers `publish`. A mail port offers `send`. A subscription port offers `subscribe`. Keep publishing and subscribing as two ports. `start` and `stop` stay on the adapter. The use case depends on the port class. The composition root passes adapters on `deps`: `new PublishPost({ posts, events })`.
 
 Search for an existing port before adding one. A second seam is a second `Port(...)` call, even when the method names match.
 

package/skills/hexok/references/use-case.md

@@ -19,23 +19,25 @@ Publishing a post is a story with a beginning and an end. Load the post, apply t
 ```ts
 class PublishPost extends UseCase('post.publish') {
   constructor(
-    private readonly posts: PostRepository,
-    private readonly events: BlogEventPublisher,
+    private readonly deps: {
+      posts: PostRepository;
+      events: BlogEventPublisher;
+    },
   ) {
     super();
   }
 
   async execute(input: { id: string }): Promise<{ id: string }> {
-    const post = await this.posts.get(input.id);
+    const post = await this.deps.posts.get(input.id);
     post.publish(new Date());
-    await this.posts.save(post);
-    await this.events.publish(new PostPublished(post.toProps()));
+    await this.deps.posts.save(post);
+    await this.deps.events.publish(new PostPublished(post.toProps()));
     return { id: post.props.id };
   }
 }
 ```
 
-The application constructs `PublishPost` with concrete adapters and calls `execute` from a gateway. One action is one class and one token. A caller who can save a draft and later publish it gets `SavePost` (`post.save`) and `PublishPost` (`post.publish`).
+The application constructs `PublishPost` with concrete adapters (`new PublishPost({ posts, events })`) and calls `execute` from a gateway. One action is one class and one token. Pass every port on `deps`, including a use case with one port. Put the core port first in the type. Optional flags chosen for that long-lived instance are a second argument, `config`. A value the caller sends on one request stays on `execute`'s input. A value declared for the whole context family stays on the factory's static spec. A caller who can save a draft and later publish it gets `SavePost` (`post.save`) and `PublishPost` (`post.publish`).
 
 Declare `execute` as a method. A class field, or an assignment after `super()`, is the wrong shape. The class is incomplete until `execute` exists, and the compiler reports the missing method.
 
@@ -49,7 +51,7 @@ Declare `execute` as a method. A class field, or an assignment after `super()`,
 | --- | --- |
 | `PublishPost.token` | The name you passed in. |
 | `execute(input)` | Required. Annotate the input and the return type on the subclass. |
-| `constructor` | Receive ports here and call `super()`. |
+| `constructor` | Ports arrive on `deps`. Optional instance settings arrive on `config`. Call `super()`. |
 
 A subclass of plain `UseCase(token)` takes one argument. Adding a context argument there is a type error. Reach for the family factory instead.
 
@@ -68,8 +70,10 @@ const ApiUseCase = UseCase.context<ApiContext>().guard((call) => {
 
 class PublishPost extends ApiUseCase('post.publish') {
   constructor(
-    private readonly posts: PostRepository,
-    private readonly events: BlogEventPublisher,
+    private readonly deps: {
+      posts: PostRepository;
+      events: BlogEventPublisher;
+    },
   ) {
     super();
   }
@@ -78,15 +82,15 @@ class PublishPost extends ApiUseCase('post.publish') {
     ctx: UseCase.Ctx<typeof ApiUseCase>,
     input: { id: string },
   ): Promise<{ id: string }> {
-    const post = await this.posts.get(input.id);
+    const post = await this.deps.posts.get(input.id);
     post.publish(new Date());
-    await this.posts.save(post);
-    await this.events.publish(new PostPublished(post.toProps()));
+    await this.deps.posts.save(post);
+    await this.deps.events.publish(new PostPublished(post.toProps()));
     return { id: post.props.id };
   }
 }
 
-await new PublishPost(posts, events).execute({ traceId: 'req-1' }, { id: 'p1' });
+await new PublishPost({ posts, events }).execute({ traceId: 'req-1' }, { id: 'p1' });
 ```
 
 A member that needs a static contract, such as a permission string or an input schema the application will read, declares that contract as the second type argument. The schema is data the guard can read. Validating the input stays in the guard or in `execute`.