@toa.io/core 1.0.0-alpha.32 → 1.0.0-alpha.321

package/transpiled/types/storages.d.ts

@@ -0,0 +1,158 @@
+import type { Readable } from 'node:stream';
+import type { Connector } from '../connector.ts';
+import type { Locator } from '../locator.ts';
+import type { Call, Inbox } from './inbox.ts';
+import type { Row, Storage as Outbox } from './outbox.ts';
+/** the RSQL tree `@rsql/parser` produces; a storage translates it into its own dialect */
+export interface Node {
+    type: 'LOGIC' | 'COMPARISON' | 'SELECTOR' | 'VALUE';
+    left?: Node;
+    right?: Node;
+    operator?: string;
+    selector?: string;
+    value?: unknown;
+}
+/** What a storage stores. `id` is the key; the upper-cased names are core's. */
+export interface Record {
+    id: string;
+    VERSION: number;
+    CREATED?: number;
+    UPDATED?: number;
+    /** a tombstone's timestamp; `null` on a live record */
+    DELETED?: number | null;
+    /** the rank of the region that last wrote it; `0` where there is one region */
+    REGION?: number;
+    [key: string]: any;
+}
+/** Everything a request query carried that was not a selector. */
+export interface Options {
+    omit?: number;
+    limit?: number;
+    /** normalised by `query/options.ts` from `'name:asc'` into pairs */
+    sort?: Array<[property: string, direction: string]>;
+    /** always includes `VERSION`, `CREATED`, `UPDATED`, `DELETED` */
+    projection?: string[];
+    sample?: number;
+    /** include tombstones; without it an observation answers `null` over one */
+    deleted?: boolean;
+    /** where a stream continues from: the token the one before it ended with */
+    token?: string;
+    /** a stream read in windows ends its first window with where changes continue from, not deeper */
+    stop?: boolean;
+}
+/** What core hands a storage, written by `Query.parse`. */
+export interface Query {
+    id?: string;
+    /** many identities at once; `State.entries` inits whichever of them are missing */
+    ids?: string[];
+    version?: number;
+    criteria?: Node;
+    search?: string;
+    options?: Options;
+}
+/**
+ * What core requires of a storage. Every member but `outbox` is called unguarded, so a
+ * storage that leaves one out throws where an operation needs it — a storage may serve
+ * only some scopes, and says so by failing rather than by declaring less.
+ */
+export interface Storage extends Connector {
+    /** scope `entry` */
+    get(query: Query): Promise<Record | null>;
+    /** scope `entries` */
+    find(query: Query): Promise<Record[]>;
+    /**
+     * scope `stream`: the parts of the collection the query selects, or of what changed in it since
+     * `options.token` — see `parts.ts`. The last part is the token; a stream that ends without it
+     * was cut.
+     */
+    stream(query?: Query): Promise<Readable>;
+    /**
+     * A transition's commit. `false` is a lost compare-and-swap, not an error. Where `row` is
+     * given, it is committed in the same transaction as the record or not at all, and where
+     * `call` is, so is that — and an identity already recorded raises `DuplicateCall` instead,
+     * having written nothing.
+     */
+    store(record: Record, row?: Row, call?: Call): Promise<boolean>;
+    /**
+     * A transition's commit over `entries`, one compare-and-swap for the whole set: every record is
+     * written, with every row, or none is. `false` is the swap lost — a record changed since it was
+     * read, or one being created that exists already — and not an error.
+     */
+    massStore(records: Record[], rows?: Row[]): Promise<boolean>;
+    /** an assignment; `null` where the query matched nothing */
+    upsert(query: Query, changeset: object, row?: Row, call?: Call): Promise<Record | null>;
+    /** get-or-create, in one indivisible step */
+    ensure(query: Query | undefined, properties: object, record: Record, row?: Row, call?: Call): Promise<Record>;
+    /** the driver's own handle, which an unmanaged operation is given as its state */
+    readonly raw: unknown;
+    /**
+     * Present only where a row can be committed atomically with the entity. Its absence is
+     * what makes the runtime publish inline, so a storage that cannot do this must not offer
+     * it: a row written outside the transaction would be a second write with a crash window
+     * in front of it, which is the defect the outbox exists to close.
+     */
+    readonly outbox?: Outbox;
+    /**
+     * Present only where a call can be recorded atomically with the entity, and only where a
+     * component declares `once`. Unlike the outbox there is no weaker thing to fall back to —
+     * a record written outside the transaction guarantees nothing — so a storage that cannot
+     * says so through `claims`, and a component that asked for it does not boot.
+     */
+    readonly inbox?: Inbox;
+    /**
+     * Whether this storage can record a call at all, which is a property of the storage rather
+     * than of the deployment it is pointed at, and so is answerable before it is connected.
+     */
+    readonly claims?: boolean;
+    /**
+     * Whether this storage applies `entity.migrations`. Absent is what a storage that does not
+     * says, and a component declaring migrations against one is refused at boot rather than
+     * starting with a structure nothing has made.
+     */
+    readonly migrates?: boolean;
+    /**
+     * Writes `record` as it stands — its `VERSION`, its timestamps, its `REGION` and whatever
+     * else it carries — where what it would replace precedes it: a lower `VERSION`, or the same
+     * `VERSION` written by a region this one outranks. `false` where it does not: nothing is
+     * written, and that is not an error.
+     *
+     * Both sides of the comparison are on the two records, so this takes nothing else. What it
+     * is for is a record that was written somewhere else and has to land here as it was, which
+     * is neither a transition nor an assignment: it is not the writer's version to increment,
+     * nor its timestamps to set.
+     */
+    converge?(record: Record): Promise<boolean>;
+    /**
+     * Whether this storage converges. Absent is what a storage that does not says, and a
+     * component of a context that converges stands down rather than running where it would
+     * never take a record from another region.
+     */
+    readonly converges?: boolean;
+}
+/**
+ * The subset of a component's entity declaration a storage reads. Structural, so that core
+ * names no type of `@toa.io/norm`, which depends on core.
+ */
+export interface Entity {
+    associated?: boolean;
+    custom?: boolean;
+    /** in the order they are applied; what a step is belongs to the storage that reads it */
+    migrations?: Migration[];
+}
+/**
+ * One file of a `migrations` directory, named after it — the component's own, or a prototype's,
+ * which every descendant applies to its collection ahead of its own.
+ */
+export interface Migration {
+    id: string;
+    steps: unknown[];
+    /** the prototype it is inherited from; absent on the component's own */
+    prototype?: string;
+}
+export interface StorageOptions {
+    /** whether the component publishes anything, and so needs a place to commit a row */
+    outbox?: boolean;
+}
+export interface Factory {
+    storage(locator: Locator, entity: Entity, options?: StorageOptions): Storage;
+}

package/transpiled/types/storages.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storages.js.map

package/transpiled/types/storages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storages.js","sourceRoot":"","sources":["../../source/types/storages.ts"],"names":[],"mappings":""}

package/transpiled/unmanaged.d.ts

@@ -0,0 +1,5 @@
+import { Operation } from './operation.ts';
+import type { Store } from './operation.ts';
+export declare class Unmanaged extends Operation {
+    protected acquire(store: Store): Promise<void>;
+}

package/transpiled/unmanaged.js

@@ -0,0 +1,7 @@
+import { Operation } from './operation.js';
+export class Unmanaged extends Operation {
+    async acquire(store) {
+        store.state = this.scope.storage.raw;
+    }
+}
+//# sourceMappingURL=unmanaged.js.map

package/transpiled/unmanaged.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unmanaged.js","sourceRoot":"","sources":["../source/unmanaged.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAG1C,MAAM,OAAO,SAAU,SAAQ,SAAS;IACnB,KAAK,CAAC,OAAO,CAAC,KAAY;QAC3C,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAA;IACtC,CAAC;CACF"}

package/src/assignment.js

@@ -1,31 +0,0 @@
-'use strict'
-
-const { Operation } = require('./operation')
-
-class Assignment extends Operation {
-  async acquire (store) {
-    store.scope = this.scope.changeset(store.request.query)
-    store.state = store.scope.get()
-  }
-
-  async commit (store) {
-    const {
-      scope,
-      state,
-      reply
-    } = store
-
-    if (reply.error !== undefined) return
-
-    scope.set(state)
-
-    const output = await this.scope.apply(scope)
-
-    // assignment returns new state by default
-    if (store.reply.output === undefined) {
-      store.reply.output = output
-    }
-  }
-}
-
-exports.Assignment = Assignment

package/src/call.js

@@ -1,42 +0,0 @@
-'use strict'
-
-const { Readable } = require('node:stream')
-const { Connector } = require('./connector')
-const { Err } = require('error-value')
-
-class Call extends Connector {
-  #transmitter
-  #contract
-
-  constructor (transmitter, contract) {
-    super()
-
-    this.#transmitter = transmitter
-    this.#contract = contract
-
-    this.depends(transmitter)
-  }
-
-  async invoke (request = {}) {
-    this.#contract.fit(request)
-
-    // avoid validation on the recipient's side
-    request.authentic = true
-
-    const reply = await this.#transmitter.request(request)
-
-    if (reply === null) return null
-    else if (reply instanceof Readable) return reply
-    else {
-      if (reply.exception !== undefined)
-        throw reply.exception
-
-      if (reply.error !== undefined)
-        return Err(reply.error.code, reply.error)
-      else
-        return reply.output
-    }
-  }
-}
-
-exports.Call = Call

package/src/cascade.js

@@ -1,35 +0,0 @@
-'use strict'
-
-const { Connector } = require('./connector')
-
-class Cascade extends Connector {
-  // #bridges
-  #last
-
-  constructor (bridges) {
-    super()
-
-    // this.#bridges = bridges
-    this.#last = bridges[bridges.length - 1]
-
-    this.depends(bridges)
-  }
-
-  async run (...args) {
-    // const reply = {}
-    //
-    // for (const bridge of this.#bridges) {
-    //   const partial = await bridge.execute(...args)
-    //
-    //   if (partial.error) return { error: partial.error }
-    //
-    //   merge(reply, partial)
-    // }
-    //
-    // return reply
-
-    return this.#last.execute(...args)
-  }
-}
-
-exports.Cascade = Cascade

package/src/component.js

@@ -1,41 +0,0 @@
-'use strict'
-
-const { console } = require('@toa.io/console')
-const { Connector } = require('./connector')
-const { NotImplementedException } = require('./exceptions')
-
-/**
- * @implements {toa.core.Component}
- */
-class Component extends Connector {
-  locator
-
-  #operations
-
-  constructor (locator, operations) {
-    super()
-
-    this.locator = locator
-    this.#operations = operations
-
-    Object.values(operations).forEach((operation) => this.depends(operation))
-  }
-
-  async open () {
-    console.info(`Runtime '${this.locator.id}' connected`)
-  }
-
-  async dispose () {
-    console.info(`Runtime '${this.locator.id}' disconnected`)
-  }
-
-  async invoke (endpoint, request) {
-    if (!(endpoint in this.#operations)) {
-      throw new NotImplementedException(`Endpoint '${endpoint}' not found in '${this.locator.id}'`)
-    }
-
-    return this.#operations[endpoint].invoke(request)
-  }
-}
-
-exports.Component = Component

package/src/composition.js

@@ -1,25 +0,0 @@
-'use strict'
-
-const { console } = require('@toa.io/console')
-const { Connector } = require('./connector')
-
-class Composition extends Connector {
-  constructor (expositions, producers, receivers, tenants) {
-    super()
-
-    if (expositions.length > 0) this.depends(expositions)
-    if (producers.length > 0) this.depends(producers)
-    if (receivers.length > 0) this.depends(receivers)
-    if (tenants.length > 0) this.depends(tenants)
-  }
-
-  async open () {
-    console.info('Composition complete')
-  }
-
-  async dispose () {
-    console.info('Composition shutdown complete')
-  }
-}
-
-exports.Composition = Composition

package/src/connector.js

@@ -1,183 +0,0 @@
-'use strict'
-
-const { console } = require('@toa.io/console')
-const { newid } = require('@toa.io/generic')
-
-/**
- * Abstract connections hierarchy
- * @implements {toa.core.Connector}
- */
-class Connector {
-  /** @type {Array<Connector>} */
-  #dependencies = []
-
-  /** @type {Array<Connector>} */
-  #links = []
-
-  /** @type {Promise} */
-  #connecting
-
-  /** @type {Promise} */
-  #disconnecting
-
-  /** @type {string} */
-  id
-  /** @type {boolean} */
-  connected = false
-
-  constructor () {
-    this.id = this.constructor.name + '#' + newid().substring(0, 8)
-  }
-
-  /**
-   * Creates a dependency and backlink with another Connector or a set of Connectors
-   *
-   * See .connect() and .disconnect()
-   *
-   * @param connector {Connector | any | Array<Connector | any>}
-   * @returns {Connector}
-   */
-  depends (connector) {
-    /** @type {Connector} */
-    let next
-
-    if (connector instanceof Array) {
-      if (connector.length === 0) throw new Error('Connectors array must not be empty')
-
-      if (connector.length > 1) {
-        next = new Connector()
-
-        for (const item of connector) {
-          this.#dependencies.push(item)
-          item.depends(next)
-        }
-      } else next = connector[0]
-    } else next = connector
-
-    this.#dependencies.push(next)
-    next.link(this)
-
-    return next
-  }
-
-  /**
-   * Creates a backlink to another Connector
-   *
-   * See .connect() and .disconnect()
-   *
-   * @param connector {Connector}
-   * @returns {void}
-   */
-  link (connector) {
-    this.#links.push(connector)
-  }
-
-  /**
-   * Connects dependants then self
-   *
-   * In case of exception disconnects with current connection interruption
-   *
-   * Method is idempotent
-   *
-   * @returns {Promise<void>}
-   */
-  async connect () {
-    if (this.#connecting) return this.#connecting
-
-    this.#disconnecting = undefined
-
-    console.debug(`Connecting '${this.id}' with ${this.#dependencies.length} dependencies...`)
-
-    this.#connecting = (async () => {
-      await Promise.all(this.#dependencies.map((connector) => connector.connect()))
-      await this.open()
-    })()
-
-    try {
-      await this.#connecting
-      this.connected = true
-    } catch (e) {
-      await this.disconnect(true)
-      throw e
-    }
-
-    console.debug(`Connector '${this.id}' connected`)
-  }
-
-  /**
-   * Disconnects self then dependants
-   *
-   * Does nothing if there are connected linked Connectors
-   *
-   * Method is idempotent
-   *
-   * @param [interrupt] {boolean}
-   * @returns {Promise<void>}
-   */
-  async disconnect (interrupt) {
-    if (interrupt !== true) await this.#connecting
-
-    if (this.#disconnecting) return this.#disconnecting
-
-    const linked = this.#links.reduce((acc, parent) => acc || parent.connected, false)
-
-    if (linked && interrupt !== true) return
-
-    this.connected = false
-    this.#connecting = undefined
-
-    this.#disconnecting = (async () => {
-      const start = +new Date()
-
-      const interval = setInterval(() => {
-        const delay = +new Date() - start
-
-        if (delay > DELAY) console.warn(`Connector ${this.id} still disconnecting (${delay})`)
-      }, DELAY)
-
-      if (interrupt !== true) await this.close()
-
-      clearInterval(interval)
-
-      await Promise.all(this.#dependencies.map(connector => connector.disconnect()))
-
-      await this.dispose()
-    })()
-
-    await this.#disconnecting
-
-    console.debug(`Connector '${this.id}' disconnected`)
-  }
-
-  async reconnect () {
-    await this.disconnect()
-    await this.connect()
-  }
-
-  debug (node = {}) {
-    node[this.id] = { connected: this.connected }
-
-    if (this.#dependencies.length > 0) for (const connector of this.#dependencies) connector.debug?.(node[this.id])
-
-    return node
-  }
-
-  /**
-   * Called on connection
-   */
-  async open () {}
-
-  /**
-   * Called on disconnection
-   */
-  async close () {}
-
-  /**
-   * Called after self and dependants disconnection is complete
-   */
-  async dispose () {}
-}
-
-const DELAY = 5000
-
-exports.Connector = Connector

package/src/context.js

@@ -1,55 +0,0 @@
-'use strict'
-
-const { Connector } = require('./connector')
-
-/**
- * @implements {toa.core.Context}
- */
-class Context extends Connector {
-  aspects
-
-  #local
-  #discover
-  #remotes = {}
-
-  constructor (local, discover, aspects = []) {
-    super()
-
-    this.aspects = aspects
-
-    this.#local = local
-    this.#discover = discover
-
-    this.depends(local)
-
-    if (aspects.length > 0) this.depends(aspects)
-  }
-
-  async apply (endpoint, request) {
-    return this.#local.invoke(endpoint, request)
-  }
-
-  async call (namespace, name, endpoint, request) {
-    const remote = await this.#remote(namespace, name)
-
-    return remote.invoke(endpoint, request)
-  }
-
-  async #remote (namespace, name) {
-    const key = namespace + '.' + name
-
-    this.#remotes[key] ??= this.#connect(namespace, name)
-
-    return this.#remotes[key]
-  }
-
-  async #connect (namespace, name) {
-    const remote = await this.#discover(namespace, name)
-
-    this.depends(remote)
-
-    return remote
-  }
-}
-
-exports.Context = Context

package/src/contract/conditions.js

@@ -1,21 +0,0 @@
-'use strict'
-
-const { SystemException } = require('../exceptions')
-
-class Conditions {
-  #schema
-
-  constructor (schema) {
-    this.#schema = schema
-  }
-
-  fit (value) {
-    const error = this.#schema.fit(value)
-
-    if (error !== null) throw new this.constructor.Exception(error)
-  }
-
-  static Exception = SystemException
-}
-
-exports.Conditions = Conditions

package/src/contract/index.js

@@ -1,7 +0,0 @@
-'use strict'
-
-const { Request } = require('./request')
-const { Reply } = require('./reply')
-
-exports.Request = Request
-exports.Reply = Reply

package/src/contract/reply.js

@@ -1,25 +0,0 @@
-'use strict'
-
-const schemas = require('./schemas')
-const { Conditions } = require('./conditions')
-const { ResponseContractException } = require('../exceptions')
-
-class Reply extends Conditions {
-  static Exception = ResponseContractException
-
-  /**
-   * @returns {toa.schema.JSON}
-   */
-  static schema (output, error) {
-    const schema = { type: 'object', properties: {}, additionalProperties: false }
-
-    if (output !== undefined) schema.properties.output = output
-
-    if (error !== undefined) schema.properties.error = error
-    else schema.properties.error = schemas.error
-
-    return schema
-  }
-}
-
-exports.Reply = Reply