@toa.io/extensions.configuration 1.0.0-alpha.282 → 1.0.0-alpha.283

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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
+
+* **cli:** an assignment hands back the new state, not nothing ([91304e9](https://github.com/toa-io/toa/commit/91304e9e9a3bba5933b7421b7a0ffff0c2e47795))
+* **storages:** take `Maybe` from core, not from the deprecated package ([bcaeeb3](https://github.com/toa-io/toa/commit/bcaeeb3c76c89af34e94ff569a210d21b7e87f64))
+
+### Features
+
+* **cli:** a type module is declarations, so it sits beside a component's source ([ca755d9](https://github.com/toa-io/toa/commit/ca755d93d1a04b7697dd0dd12eb59e5b6e2a71d1))
+* **cli:** the built-in components ship types generated from their manifests ([bd7db9e](https://github.com/toa-io/toa/commit/bd7db9e88e46c1060223761898932239127f389a))
+* **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/components/configuration.values/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './toa.js'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/configuration.values/types/toa.d.ts

@@ -0,0 +1,68 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { Query, RemoteError } from '@toa.io/core'
+import type { Readable } from 'node:stream'
+
+export interface Entity {
+  component: string
+  epoch: string
+  configuration: Record<string, unknown>
+  originator: string
+  id: string
+  _version?: number
+  _created?: number
+  _updated?: number
+  _deleted?: number | null
+}
+
+export type GetInput = {
+  component: string
+  epoch?: string
+}
+
+export type GetOutput = {
+  configuration: Record<string, unknown>
+  schema?: Record<string, unknown>
+  epoch: string
+} | null
+
+export type FetchInput = Array<{
+  component: string
+  epoch: string
+}>
+
+export type FetchOutput = Array<{
+  component: string
+  epoch: string
+  configuration: Record<string, unknown> | null
+  created: number
+}>
+
+export type ListOutput = Array<{
+  component: string
+  epoch: string
+  schema: Record<string, unknown>
+  configuration: Record<string, unknown>
+}>
+
+export type CreateInput = {
+  component: string
+  configuration: Record<string, unknown>
+  originator: {
+    id: string
+  }
+}
+
+export interface Component {
+  get: (request: { input: GetInput, task?: boolean }) => Promise<GetOutput>
+  fetch: (request: { input: FetchInput, task?: boolean }) => Promise<FetchOutput>
+  list: (request: { input?: null, task?: boolean }) => Promise<ListOutput>
+  create: (request: { input: CreateInput, task?: boolean }) => Promise<unknown | RemoteError<"UNKNOWN_COMPONENT" | "INVALID_CONFIGURATION">>
+  assign: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+  ensure: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+  enumerate: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity[]>
+  observe: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity | null>
+  stream: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Readable>
+  terminate: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.configuration",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.283",
   "type": "module",
   "description": "Toa Configuration",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -23,11 +23,11 @@
     "prepack": "npm run build:ui",
     "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f",
+  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1",
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.282",
-    "@toa.io/generic": "1.0.0-alpha.282",
-    "@toa.io/schemas": "1.0.0-alpha.282",
+    "@toa.io/core": "1.0.0-alpha.283",
+    "@toa.io/generic": "1.0.0-alpha.283",
+    "@toa.io/schemas": "1.0.0-alpha.283",
     "openspan": "1.0.0-alpha.277"
   }
 }

package/source/Secret.ts

@@ -1,8 +1,11 @@
 import { inspect } from 'node:util'
-import type { Secret as Contract } from '@toa.io/types'
 
-/** A configuration value that must not leak: a string only to whoever asks for it. */
-export class Secret implements Contract {
+/**
+ * A configuration value that must not leak: a string only to whoever asks for it.
+ *
+ * This is what a value declared `format: secret` is on a component's context.
+ */
+export class Secret {
   readonly #value: string
 
   public constructor (value: string) {

package/source/context.ts

@@ -0,0 +1,13 @@
+import type { Manifest } from './manifest.js'
+import type { Contribution } from '@toa.io/core'
+
+/** What this extension puts on the context of a component that declares it. */
+export function context (declaration: Manifest): Contribution {
+  const contribution: Contribution = { name: 'configuration', schema: declaration.schema }
+
+  // a value the schema declares a secret is one on the context, not a string
+  if (JSON.stringify(declaration.schema).includes('"secret"'))
+    contribution.imports = { '@toa.io/extensions.configuration': ['Secret'] }
+
+  return contribution
+}

package/source/index.ts

@@ -2,3 +2,9 @@ export { manifest } from './manifest.js'
 export { deployment, describe } from './deployment.js'
 export { components } from './Composition.js'
 export { Factory } from './Factory.js'
+
+// what a value declared `format: secret` is on a component's context
+export { Secret } from './Secret.js'
+
+// what this extension puts on a component's context
+export { context } from './context.js'

package/transpiled/Secret.d.ts

@@ -1,7 +1,10 @@
 import { inspect } from 'node:util';
-import type { Secret as Contract } from '@toa.io/types';
-/** A configuration value that must not leak: a string only to whoever asks for it. */
-export declare class Secret implements Contract {
+/**
+ * A configuration value that must not leak: a string only to whoever asks for it.
+ *
+ * This is what a value declared `format: secret` is on a component's context.
+ */
+export declare class Secret {
     #private;
     constructor(value: string);
     unwrap(): string;

package/transpiled/Secret.js

@@ -1,5 +1,9 @@
 import { inspect } from 'node:util';
-/** A configuration value that must not leak: a string only to whoever asks for it. */
+/**
+ * A configuration value that must not leak: a string only to whoever asks for it.
+ *
+ * This is what a value declared `format: secret` is on a component's context.
+ */
 export class Secret {
     #value;
     constructor(value) {

package/transpiled/Secret.js.map

@@ -1 +1 @@
-{"version":3,"file":"Secret.js","sourceRoot":"","sources":["../source/Secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,sFAAsF;AACtF,MAAM,OAAO,MAAM;IACR,MAAM,CAAQ;IAEvB,YAAoB,KAAa;QAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;IACrB,CAAC;IAEM,MAAM;QACX,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;IAEM,QAAQ;QACb,OAAO,QAAQ,CAAA;IACjB,CAAC;IAEM,MAAM;QACX,OAAO,QAAQ,CAAA;IACjB,CAAC;IAEM,CAAC,OAAO,CAAC,MAAM,CAAC;QACrB,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAA"}
+{"version":3,"file":"Secret.js","sourceRoot":"","sources":["../source/Secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC;;;;GAIG;AACH,MAAM,OAAO,MAAM;IACR,MAAM,CAAQ;IAEvB,YAAoB,KAAa;QAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;IACrB,CAAC;IAEM,MAAM;QACX,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;IAEM,QAAQ;QACb,OAAO,QAAQ,CAAA;IACjB,CAAC;IAEM,MAAM;QACX,OAAO,QAAQ,CAAA;IACjB,CAAC;IAEM,CAAC,OAAO,CAAC,MAAM,CAAC;QACrB,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAA"}

package/transpiled/context.d.ts

@@ -0,0 +1,4 @@
+import type { Manifest } from './manifest.js';
+import type { Contribution } from '@toa.io/core';
+/** What this extension puts on the context of a component that declares it. */
+export declare function context(declaration: Manifest): Contribution;

package/transpiled/context.js

@@ -0,0 +1,9 @@
+/** What this extension puts on the context of a component that declares it. */
+export function context(declaration) {
+    const contribution = { name: 'configuration', schema: declaration.schema };
+    // a value the schema declares a secret is one on the context, not a string
+    if (JSON.stringify(declaration.schema).includes('"secret"'))
+        contribution.imports = { '@toa.io/extensions.configuration': ['Secret'] };
+    return contribution;
+}
+//# sourceMappingURL=context.js.map

package/transpiled/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../source/context.ts"],"names":[],"mappings":"AAGA,+EAA+E;AAC/E,MAAM,UAAU,OAAO,CAAE,WAAqB;IAC5C,MAAM,YAAY,GAAiB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAA;IAExF,2EAA2E;IAC3E,IAAI,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;QACzD,YAAY,CAAC,OAAO,GAAG,EAAE,kCAAkC,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAA;IAE3E,OAAO,YAAY,CAAA;AACrB,CAAC"}

package/transpiled/index.d.ts

@@ -2,3 +2,5 @@ export { manifest } from './manifest.js';
 export { deployment, describe } from './deployment.js';
 export { components } from './Composition.js';
 export { Factory } from './Factory.js';
+export { Secret } from './Secret.js';
+export { context } from './context.js';

package/transpiled/index.js

@@ -2,4 +2,8 @@ export { manifest } from './manifest.js';
 export { deployment, describe } from './deployment.js';
 export { components } from './Composition.js';
 export { Factory } from './Factory.js';
+// what a value declared `format: secret` is on a component's context
+export { Secret } from './Secret.js';
+// what this extension puts on a component's context
+export { context } from './context.js';
 //# sourceMappingURL=index.js.map

package/transpiled/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,qEAAqE;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,oDAAoD;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}