@toa.io/core 1.0.0-alpha.282 → 1.0.0-alpha.283

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.283](https://github.com/toa-io/toa/compare/v1.0.0-alpha.282...v1.0.0-alpha.283) (2026-09-04)
+
+### Bug Fixes
+
+* **core:** an operation returns the errors it declares, and nothing else ([1c2b819](https://github.com/toa-io/toa/commit/1c2b8193ae7fbe86bc1a25053a6044ee4dd16a4a))
+* **storages:** take `Maybe` from core, not from the deprecated package ([bcaeeb3](https://github.com/toa-io/toa/commit/bcaeeb3c76c89af34e94ff569a210d21b7e87f64))
+
+### Features
+
+* **extensions:** an extension declares what it puts on a component's context ([133bc2a](https://github.com/toa-io/toa/commit/133bc2aad1e45a2d4aa68a08a5e44ca48d3b7414))
+
+
 # [1.0.0-alpha.282](https://github.com/toa-io/toa/compare/v1.0.0-alpha.281...v1.0.0-alpha.282) (2026-09-03)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.283",
   "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -22,10 +22,10 @@
   },
   "dependencies": {
     "@rsql/parser": "1.6.0",
-    "@toa.io/generic": "1.0.0-alpha.282",
+    "@toa.io/generic": "1.0.0-alpha.283",
     "js-yaml": "5.4.1",
     "openspan": "1.0.0-alpha.277",
     "uuid": "14.0.2"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
+  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
 }

package/src/contract/reply.js

@@ -1,4 +1,3 @@
-import * as schemas from './schemas/index.js'
 import { Contract } from './contract.js'
 import { ResponseContractException } from '../exceptions.js'
 
@@ -25,21 +24,25 @@ export class Reply extends Contract {
       schema.properties.output = output
     }
 
-    if (errors !== undefined)
-      schema.properties.error = {
-        type: 'object',
-        properties: {
-          code: {
-            enum: errors
+    /*
+     * An error a caller is meant to handle is one the operation states. Where none are
+     * stated, an error is not a reply this operation makes — it is a mistake, and the
+     * contract says so rather than passing an undeclared code on to whoever called.
+     */
+    schema.properties.error = errors === undefined
+      ? false
+      : {
+          type: 'object',
+          properties: {
+            code: {
+              enum: errors
+            },
+            message: {
+              type: 'string'
+            }
           },
-          message: {
-            type: 'string'
-          }
-        },
-        required: ['code']
-      }
-    else
-      schema.properties.error = schemas.error
+          required: ['code']
+        }
 
     return schema
   }

package/types/call.d.ts

@@ -0,0 +1,13 @@
+import type { Request } from './request.js'
+
+/**
+ * How an endpoint is called. What it resolves to is what the operation declares — `toa types`
+ * writes that per operation, and these are what a hand-written context says instead.
+ */
+export type Call<Output = any, Input = any> = (request: Request<Input>) => Promise<Output>
+
+export type Observation<Output = any, Input = never, Entity = unknown> =
+  (request: Request<Input, Entity>) => Promise<Output extends unknown[] ? Output : Output | null>
+
+export type Transition<Output = any, Input = never, Entity = unknown> =
+  (request: Request<Input, Entity>) => Promise<Output | null>

package/types/extensions.d.ts

@@ -47,6 +47,25 @@ export interface Factory {
   receiver? (receiver: _core.Receiver, locator: _core.Locator): _core.Receiver
 }
 
+/**
+ * What an extension puts on a component's context, as the extension states it. How it is
+ * presented there is the bridge's — a bash bridge has no context to put anything on — and
+ * what is declared here is the key and what it holds.
+ */
+export interface Contribution {
+  /** the key on the context */
+  name: string
+
+  /** what the key holds, as TypeScript */
+  type?: string
+
+  /** what `type` names, by the module it comes from */
+  imports?: Record<string, string[]>
+
+  /** a JSON Schema to read the type from instead, where a component states one */
+  schema?: object
+}
+
 export interface Aspect extends _core.Connector {
   name: string
 

package/types/guard.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs on every change to an entity's state, before the contract is applied. `false` refuses
+ * the change as `EntityGuard`.
+ */
+export type Guard<T, C = unknown> = (state: T, origin: T | null, context: C) => boolean

package/types/index.ts

@@ -14,4 +14,8 @@ export type { Exception } from './exception.js'
 export { Locator } from './locator.js'
 export type { Receiver } from './receiver.js'
 export type { Message } from './message.js'
-export type { Request, Query, Reply, Source } from './request.js'
+export type { Maybe, Request, Query, Reply, RemoteError, Source } from './request.js'
+export type { Event } from './state.js'
+export type { Guard } from './guard.js'
+export type { Call, Observation, Transition } from './call.js'
+export type { Contribution } from './extensions.js'

package/types/request.d.ts

@@ -1,6 +1,10 @@
 import { Exception } from './exception.js'
 
-export interface Query {
+/**
+ * What a call asks for. `Entity` is the record it is about, which narrows the projection;
+ * left out, any name is accepted.
+ */
+export interface Query<Entity = any> {
   id?: string
   ids?: Array<string>
   criteria?: string
@@ -9,7 +13,7 @@ export interface Query {
   omit?: number
   limit?: number
   sort?: Array<string>
-  projection?: Array<string>
+  projection?: Array<string & keyof Entity>
   version?: number
   deleted?: boolean
 }
@@ -22,15 +26,28 @@ export type Source =
   | { namespace: string, component: string, event: string }
   | { service: string }
 
-export interface Request {
-  input?: any
-  query?: Query
+export interface Request<Input = any, Entity = any> {
+  input?: Input
+  query?: Query<Entity>
+  /** What the operation acquires, where the caller supplies it rather than the storage. */
+  entity?: Entity
   authentic?: boolean
   task?: boolean
   telemetry?: string // W3C traceparent
   source?: Source
 }
 
+/**
+ * An error an operation declares and returns. A call resolves to it rather than throwing:
+ * only an exception is thrown.
+ */
+export interface RemoteError<Code extends string = string> extends Error {
+  code: Code
+}
+
+/** What an operation returns where it may refuse: the value, or the error it refused with. */
+export type Maybe<T> = T | Error
+
 export interface Reply {
   output?: any
   error?: object

package/types/state.d.ts

@@ -5,12 +5,12 @@ declare namespace toa.core {
 
   namespace transition {
 
-    type Event = {
+    type Event<State = Object, Trailers = Object> = {
       /** the pre-image; null when the entity did not exist before */
-      origin: Object | null
-      state: Object
+      origin: State | null
+      state: State
       /** out-of-band values an algorithm wrote into `state._trailers`; must be serializable */
-      trailers?: Object
+      trailers?: Trailers
       input?: Object
     }
 
@@ -35,4 +35,4 @@ declare namespace toa.core {
 }
 
 export type State = toa.core.State
-export type Event = toa.core.transition.Event
+export type Event<State = Object, Trailers = Object> = toa.core.transition.Event<State, Trailers>