@toa.io/core 1.0.0-alpha.266 → 1.0.0-alpha.270

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 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.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
+
+
+### Bug Fixes
+
+* **core:** apply the input default on a remote call ([341699b](https://github.com/toa-io/toa/commit/341699b26c9299963a898368671633a9b3fb97ed))
+
+
+### Performance Improvements
+
+* **core:** do not snapshot a record an operation cannot commit ([a5e695b](https://github.com/toa-io/toa/commit/a5e695b0b1d4b00a91e40336deecd476c9646c89))
+* **core:** keep the parsed criteria of a query ([7efc694](https://github.com/toa-io/toa/commit/7efc694814c2a071ae7e48dbf1c6014db6025a9f))
+* stop rebuilding per-call values that never change ([4202504](https://github.com/toa-io/toa/commit/4202504c33fb9ef9694f9995f3d0397d3a186438))
+
+
+
+
+
 # [1.0.0-alpha.266](https://github.com/toa-io/toa/compare/v1.0.0-alpha.265...v1.0.0-alpha.266) (2026-08-29)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.266",
+  "version": "1.0.0-alpha.270",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -24,8 +24,8 @@
     "@toa.io/generic": "1.0.0-alpha.254",
     "@toa.io/yaml": "1.0.0-alpha.254",
     "error-value": "0.3.0",
-    "openspan": "1.0.0-alpha.264",
+    "openspan": "1.0.0-alpha.270",
     "uuid": "11.1.1"
   },
-  "gitHead": "0d2b83ff9ed6bf6d9fee7bf00f979b9ee38e9713"
+  "gitHead": "94400bdd411b4c25074ffcf58184580ddd060268"
 }

package/src/call.js

@@ -21,14 +21,16 @@ class Call extends Connector {
   }
 
   async invoke (request = {}) {
-    request.input ??= null
-
     // the caller may have attributed the call itself, as the node bridge does
     if (this.#source !== undefined)
       request.source ??= this.#source
 
+    // fitting first lets the input schema supply its default;
+    // an operation that takes no input still has to send an explicit null
     this.#contract.fit(request)
 
+    request.input ??= null
+
     // avoid validation on the recipient's side
     request.authentic = true
 

package/src/component.js

@@ -13,6 +13,9 @@ class Component extends Connector {
   /** @protected */
   kind = 'server'
 
+  /** @type {Record<string, object>} span options per endpoint */
+  #spans = {}
+
   constructor (locator, operations) {
     super()
 
@@ -23,8 +26,9 @@ class Component extends Connector {
   }
 
   async invoke (endpoint, request) {
-    assert.ok(endpoint in this.operations,
-      `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
+    if (!(endpoint in this.operations))
+      // `assert.fail`, not `assert.ok`: the message is built only when it is needed
+      assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
     // if the request carries no telemetry, the trace starts here
     const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
@@ -38,14 +42,7 @@ class Component extends Connector {
 
   /** @private */
   async process (endpoint, request) {
-    const options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
-
-    // the server span is emitted by the component itself,
-    // while the client span belongs to the calling service and inherits it from the context
-    if (this.kind === 'server')
-      options.service = this.locator.id
-
-    return console.span(options, async () => {
+    return console.span(this.span(endpoint), async () => {
       const reply = await this.operations[endpoint].invoke(request)
 
       if (reply?.exception !== undefined) {
@@ -60,6 +57,29 @@ class Component extends Connector {
       return reply
     })
   }
+
+  /**
+   * The span of an endpoint never changes, so it is built once. Not in the constructor:
+   * `kind` is a field of the subclass, and those are assigned after this one is built.
+   *
+   * @private
+   */
+  span (endpoint) {
+    let options = this.#spans[endpoint]
+
+    if (options === undefined) {
+      options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
+
+      // the server span is emitted by the component itself, while the client span
+      // belongs to the calling service and inherits it from the context
+      if (this.kind === 'server')
+        options.service = this.locator.id
+
+      this.#spans[endpoint] = options
+    }
+
+    return options
+  }
 }
 
 exports.Component = Component

package/src/entities/entity.js

@@ -10,15 +10,28 @@ class Entity {
   #guards
   #origin = null
   #state
+  #mutable = true
 
-  constructor (schema, argument, guards) {
+  /**
+   * @param {boolean} [mutable] whether the entity may be modified and committed
+   */
+  constructor (schema, argument, guards, mutable = true) {
     this.#schema = schema
     this.#guards = guards
 
     if (typeof argument === 'object') {
-      const object = structuredClone(argument)
-      this.#set(object)
-      this.#origin = argument
+      /*
+       * The origin is the pre-image a commit diffs the new state against. An operation
+       * that cannot commit has nothing to diff, so it takes the record as it came from
+       * the storage instead of paying for a deep copy of every record it read.
+       */
+      this.#mutable = mutable
+
+      if (mutable) {
+        this.#set(structuredClone(argument))
+        this.#origin = argument
+      } else
+        this.#set(argument)
     } else {
       const id = argument === undefined ? newid() : argument
       this.#init(id)
@@ -30,6 +43,9 @@ class Entity {
   }
 
   set (value, optional = false) {
+    if (!this.#mutable)
+      throw new Error('Entity acquired by a read-only operation cannot be modified')
+
     if (!optional)
       this.#guard(value)
 

package/src/entities/factory.js

@@ -22,12 +22,12 @@ class Factory {
     return new Entity(this.#schema, id, this.#guards)
   }
 
-  object (record) {
-    return new Entity(this.#schema, record, this.#guards)
+  object (record, mutable = true) {
+    return new Entity(this.#schema, record, this.#guards, mutable)
   }
 
-  objects (recordset, init) {
-    const set = recordset.map((record) => this.object(record))
+  objects (recordset, init, mutable = true) {
+    const set = recordset.map((record) => this.object(record, mutable))
 
     if (init !== undefined) 
       for (const id of init)

package/src/operation.js

@@ -7,6 +7,15 @@ const { Readable } = require('node:stream')
 class Operation extends Connector {
   scope
 
+  /**
+   * Whether what this operation acquires may be modified and committed. Only a
+   * transition commits, and only a commit needs the pre-image an entity keeps
+   * to diff the new state against.
+   *
+   * @protected
+   */
+  mutable = false
+
   #cascade
   #contracts
   #query
@@ -83,7 +92,7 @@ class Operation extends Connector {
     if (query === undefined)
       throw new RequestContractException('Request query is required')
 
-    return this.scope[this.#scope](query)
+    return this.scope[this.#scope](query, this.mutable)
   }
 }
 

package/src/query.js

@@ -7,6 +7,9 @@ class Query {
   #properties
   #system
 
+  /** @type {Map<string, object>} parsed criteria by their expression */
+  #asts = new Map()
+
   constructor (properties) {
     this.#properties = properties
     this.#system = Object.keys(properties).filter((key) => properties[key].system === true)
@@ -26,7 +29,7 @@ class Query {
     if (id !== undefined) result.id = id
     if (ids !== undefined) result.ids = ids
     if (version !== undefined) result.version = version
-    if (criteria !== undefined) result.criteria = parse.criteria(criteria, this.#properties)
+    if (criteria !== undefined) result.criteria = this.#criteria(criteria)
     if (search !== undefined) result.search = search
     if (options !== undefined) result.options = options
 
@@ -38,6 +41,31 @@ class Query {
 
     return parse.options(options, this.#properties, this.#system)
   }
+
+  /**
+   * Lexing an RSQL expression is the most expensive thing this class does, and the same
+   * expression arrives over and over: a route builds it from its own declaration and the
+   * request parameters. The tree is only read downstream — a storage builds a fresh query
+   * from it — so it is kept rather than parsed again.
+   *
+   * Expressions come from the client, hence the bound. An invalid one throws before it
+   * reaches the cache.
+   */
+  #criteria (criteria) {
+    const known = this.#asts.get(criteria)
+
+    if (known !== undefined) return known
+
+    const ast = parse.criteria(criteria, this.#properties)
+
+    if (this.#asts.size >= LIMIT) this.#asts.clear()
+
+    this.#asts.set(criteria, ast)
+
+    return ast
+  }
 }
 
+const LIMIT = 1024
+
 exports.Query = Query

package/src/receiver.js

@@ -33,6 +33,12 @@ class Receiver extends Connector {
 
   #bridge
 
+  /** @type {object} */
+  #delivery
+
+  /** @type {object} */
+  #processing
+
   constructor (definition, local, bridge) {
     super()
 
@@ -51,6 +57,27 @@ class Receiver extends Connector {
 
     this.depends(local)
     if (bridge !== undefined) this.depends(bridge)
+
+    /*
+     * The delivery span is created on behalf of the messaging destination, so that
+     * each consumer forms its own complete producer/consumer pair, and service graphs
+     * display fan-out correctly: producer -> destination -> each consumer
+     * (Tempo pairs spans one-to-one, thus multiple consumers can not pair
+     * with a single producer span, see grafana/tempo#5408)
+     */
+    this.#delivery = {
+      name: `${this.#label} deliver`,
+      kind: 'producer',
+      service: this.#destination,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
+
+    this.#processing = {
+      name: `${this.#label} process`,
+      kind: 'consumer',
+      service: local.locator.id,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
   }
 
   /** @hot */
@@ -77,28 +104,7 @@ class Receiver extends Connector {
   }
 
   async #process (request) {
-    /*
-     * The delivery span is created on behalf of the messaging destination, so that
-     * each consumer forms its own complete producer/consumer pair, and service graphs
-     * display fan-out correctly: producer -> destination -> each consumer
-     * (Tempo pairs spans one-to-one, thus multiple consumers can not pair
-     * with a single producer span, see grafana/tempo#5408)
-     */
-    const delivery = {
-      name: `${this.#label} deliver`,
-      kind: 'producer',
-      service: this.#destination,
-      attributes: { 'messaging.destination.name': this.#destination }
-    }
-
-    const options = {
-      name: `${this.#label} process`,
-      kind: 'consumer',
-      service: this.#local.locator.id,
-      attributes: { 'messaging.destination.name': this.#destination }
-    }
-
-    return console.span(delivery, async () => console.span(options, async () => {
+    return console.span(this.#delivery, async () => console.span(this.#processing, async () => {
       try {
         await this.#local.invoke(this.#endpoint, request)
       } catch (error) {

package/src/remote.js

@@ -7,8 +7,9 @@ class Remote extends Component {
   kind = 'client'
 
   explain (endpoint) {
-    assert.ok(endpoint in this.operations,
-      `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
+    if (!(endpoint in this.operations))
+      // `assert.fail`, not `assert.ok`: the message is built only when it is needed
+      assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
     return this.operations[endpoint].explain()
   }

package/src/state.js

@@ -24,7 +24,7 @@ class State {
     return this.#entities.fit(values)
   }
 
-  async object (query) {
+  async object (query, mutable = true) {
     const record = await this.storage.get(query)
 
     if (record === null) {
@@ -35,15 +35,15 @@ class State {
 
       return null
     } else
-      return this.#entities.object(record)
+      return this.#entities.object(record, mutable)
   }
 
-  async objects (query) {
+  async objects (query, mutable = true) {
     const recordset = await this.storage.find(query)
     const missing = this.#associated && query.ids !== undefined && recordset.length < query.ids.length
     const init = missing ? query.ids.filter((id) => !recordset.some((record) => record.id === id)) : undefined
     
-    return this.#entities.objects(recordset, init)
+    return this.#entities.objects(recordset, init, mutable)
   }
 
   async stream (query) {
@@ -69,7 +69,7 @@ class State {
     const record = await this.storage.ensure(query, properties, object.get())
 
     if (record.id !== blank.id) // exists
-      return this.#entities.object(record)
+      return this.#entities.object(record, NOT_MUTABLE)
 
     const event = object.event(input)
 
@@ -132,4 +132,7 @@ class State {
   }
 }
 
+/** an effect never commits what `ensure` hands it, see `Effect` */
+const NOT_MUTABLE = false
+
 exports.State = State

package/src/transition.js

@@ -5,6 +5,9 @@ const { Operation } = require('./operation')
 const { StateConcurrencyException, StateNotFoundException } = require('./exceptions')
 
 class Transition extends Operation {
+  /** a transition is the only operation that commits */
+  mutable = true
+
   #concurrency
 
   constructor (cascade, scope, contract, query, definition) {

package/test/entities/entity.test.js

@@ -14,6 +14,37 @@ describe('argument', () => {
 
     expect(entity.get()).toEqual(state)
   })
+
+  it('should snapshot the record it may commit', () => {
+    const record = fixtures.state()
+    const entity = new Entity(fixtures.schema, record)
+
+    expect(entity.get()).not.toBe(record)
+    expect(entity.event().origin).toBe(record)
+  })
+})
+
+describe('read-only', () => {
+  it('should take the record as it came', () => {
+    const record = fixtures.state()
+    const entity = new Entity(fixtures.schema, record, undefined, false)
+
+    // no pre-image to diff against, hence no copy of it
+    expect(entity.get()).toBe(record)
+  })
+
+  it('should still report a tombstone', () => {
+    const record = { ...fixtures.state(), _deleted: Date.now() }
+    const entity = new Entity(fixtures.schema, record, undefined, false)
+
+    expect(entity.deleted).toBe(true)
+  })
+
+  it('should refuse to be modified', () => {
+    const entity = new Entity(fixtures.schema, fixtures.state(), undefined, false)
+
+    expect(() => entity.set(entity.get())).toThrow('read-only')
+  })
 })
 
 describe('tombstone', () => {

package/test/entities/factory.test.js

@@ -30,7 +30,8 @@ it('should create instance', () => {
   const object = factory.object(fixtures.entity)
 
   expect(object).toBeInstanceOf(mock.Entity)
-  expect(object.constructor).toHaveBeenCalledWith(fixtures.schema, fixtures.entity, expect.any(Function))
+  expect(object.constructor)
+    .toHaveBeenCalledWith(fixtures.schema, fixtures.entity, expect.any(Function), true)
 })
 
 it('should create set', () => {
@@ -39,7 +40,8 @@ it('should create set', () => {
   expect(objects).toBeInstanceOf(mock.EntitySet)
 
   const instances = fixtures.set.map((entity, index) => {
-    expect(mock.Entity).toHaveBeenNthCalledWith(index + 1, fixtures.schema, entity, expect.any(Function))
+    expect(mock.Entity)
+      .toHaveBeenNthCalledWith(index + 1, fixtures.schema, entity, expect.any(Function), true)
 
     return mock.Entity.mock.instances[index]
   })

package/test/query.test.js

@@ -22,6 +22,23 @@ describe('criteria', () => {
     expect(query.criteria).toEqual(fixtures.samples.simple.parsed.criteria)
   })
 
+  it('should keep a parsed criteria', () => {
+    const instance = new Query(fixtures.samples.simple.properties)
+
+    const first = instance.parse(fixtures.samples.simple.query).criteria
+    const second = instance.parse(fixtures.samples.simple.query).criteria
+
+    expect(second).toBe(first)
+  })
+
+  it('should not keep an invalid criteria', () => {
+    const instance = new Query(fixtures.samples.simple.properties)
+    const query = { criteria: 'nonexistent==1' }
+
+    expect(() => instance.parse(query)).toThrow()
+    expect(() => instance.parse(query)).toThrow()
+  })
+
   it('should parse criteria with type coercion', () => {
     const instance = new Query(fixtures.samples.extended.properties)
     const query = instance.parse(fixtures.samples.extended.query)

package/test/state.test.js

@@ -16,7 +16,22 @@ it('should provide object', async () => {
 
   expect(fixtures.storage.get).toHaveBeenCalledWith(fixtures.query)
   expect(entity).toStrictEqual(fixtures.factory.object.mock.results[0].value)
-  expect(fixtures.factory.object).toHaveBeenCalledWith(fixtures.storage.get.mock.results[0].value)
+  expect(fixtures.factory.object)
+    .toHaveBeenCalledWith(fixtures.storage.get.mock.results[0].value, true)
+})
+
+it('should provide read-only object', async () => {
+  await state.object(fixtures.query, false)
+
+  expect(fixtures.factory.object)
+    .toHaveBeenCalledWith(fixtures.storage.get.mock.results[0].value, false)
+})
+
+it('should provide read-only objects', async () => {
+  await state.objects(fixtures.query, false)
+
+  expect(fixtures.factory.objects)
+    .toHaveBeenCalledWith(fixtures.storage.find.mock.results[0].value, undefined, false)
 })
 
 it('should store entity', async () => {

package/types/entity.d.ts

@@ -8,9 +8,9 @@ declare namespace toa.core {
     interface Factory {
       init(id: string): Entity
 
-      object(record: Object): Entity
+      object(record: Object, mutable?: boolean): Entity
 
-      objects(recordset: Object[]): Entity[]
+      objects(recordset: Object[], init?: string[], mutable?: boolean): Entity[]
 
       changeset(query: _storages.Query): Changeset
     }

package/types/state.d.ts

@@ -16,9 +16,9 @@ declare namespace toa.core {
   interface State {
     init(id: string): _entity.Entity
 
-    object(query: _storages.Query): Promise<_entity.Entity>
+    object(query: _storages.Query, mutable?: boolean): Promise<_entity.Entity>
 
-    objects(query: _storages.Query): Promise<_entity.Entity[]>
+    objects(query: _storages.Query, mutable?: boolean): Promise<_entity.Entity[]>
 
     changeset(query: _storages.Query): _entity.Changeset