@toa.io/norm 1.0.0-alpha.3 → 1.0.0-alpha.300

package/test/manifest.test.js

@@ -0,0 +1,126 @@
+import { it, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolve } from 'node:path'
+
+import { component } from '../src/component.js'
+import { plain, revive } from '../src/manifest.js'
+
+/** the prototype itself: an entity, operations and events, and no prototype of its own */
+const PROTOTYPE = resolve(import.meta.dirname, '../../prototype')
+
+/** a component on the default prototype, with an entity, events and receivers */
+const COMPONENT = resolve(
+  import.meta.dirname,
+  '../../../features/steps/.workspace/components/collection/external.consumer'
+)
+
+/** a component whose prototype is a directory of the workspace's own */
+const EXTENDED = resolve(
+  import.meta.dirname,
+  '../../../features/steps/.workspace/components/collection/configuration.extended'
+)
+
+const carry = (manifest) => JSON.parse(JSON.stringify(plain(manifest)))
+
+describe('a manifest carried through a file', () => {
+  for (const [name, path] of [
+    ['the prototype', PROTOTYPE],
+    ['a component', COMPONENT]
+  ])
+    it(`comes back the same: ${name}`, async () => {
+      const manifest = await component(path)
+
+      assert.deepStrictEqual(revive(carry(manifest), path), manifest)
+    })
+
+  it('does not carry a key with no value', () => {
+    const carried = plain({ name: 'a', namespace: 'b', path: '/x', operations: { echo: { input: undefined } } })
+
+    assert.deepStrictEqual(carried.operations.echo, {})
+  })
+
+  it('leaves the manifest it was given alone', async () => {
+    const manifest = await component(COMPONENT)
+    const before = JSON.stringify(manifest)
+
+    plain(manifest)
+
+    assert.strictEqual(JSON.stringify(manifest), before)
+  })
+
+  it('is read beside the component wherever it is', async () => {
+    const carried = carry(await component(COMPONENT))
+    const revived = revive(carried, '/composition/external-consumer')
+
+    assert.strictEqual(revived.path, '/composition/external-consumer')
+
+    // what the component declares is in the component
+    assert.strictEqual(
+      revived.receivers['something_happened'].path,
+      '/composition/external-consumer'
+    )
+  })
+
+  it('reads what is inherited where the prototype is', async () => {
+    const prototype = (await component(COMPONENT)).prototype.path
+    const revived = revive(carry(await component(COMPONENT)), '/composition/external-consumer')
+
+    // an event of the prototype's is in the prototype, wherever the component is
+    assert.strictEqual(revived.events.created.path, prototype)
+  })
+
+  it('carries what is inherited by the package that holds it', async () => {
+    const carried = carry(await component(COMPONENT))
+
+    assert.strictEqual(carried.prototype.path, '@toa.io/prototype')
+    assert.strictEqual(carried.events.created.path, '@toa.io/prototype')
+    assert.strictEqual(carried.receivers['something_happened'].path, '.')
+  })
+})
+
+describe('what cannot be carried', () => {
+  it('leaves out where the manifest is and what only a deploy reads', async () => {
+    const manifest = await component(PROTOTYPE)
+
+    manifest.packages = { cloudinary: '2.11.0' }
+
+    const carried = plain(manifest)
+
+    assert.ok(!('locator' in carried))
+    assert.ok(!('path' in carried))
+    assert.ok(!('packages' in carried))
+  })
+
+  it('refuses a prototype an image would not have', async () => {
+    const manifest = await component(EXTENDED)
+
+    assert.throws(() => plain(manifest), /is in no package, so an image cannot carry what is in it/)
+  })
+
+  it('refuses a path inside the component it does not know about', () => {
+    assert.throws(
+      () => plain({ name: 'a', namespace: 'b', path: '/x', invented: { at: '/x/y' } }),
+      /carries a path of the machine that read it/
+    )
+  })
+
+  it('refuses a component directory it does not know about', async () => {
+    const manifest = await component(PROTOTYPE)
+
+    manifest.invented = { at: COMPONENT }
+
+    assert.throws(() => plain(manifest), /carries a path of the machine that read it/)
+  })
+
+  it('leaves a value of the application\'s own alone', () => {
+    const carried = plain({
+      name: 'a',
+      namespace: 'b',
+      path: '/x',
+      extensions: { exposition: { routes: [{ path: '/accounts' }] } }
+    })
+
+    assert.strictEqual(carried.extensions.exposition.routes[0].path, '/accounts')
+  })
+})

package/test/shortcuts.fixtures.js

@@ -1,14 +1,9 @@
-'use strict'
+import { generate } from 'randomstring'
+import { random } from '@toa.io/generic'
 
-const { generate } = require('randomstring')
-const { random } = require('@toa.io/generic')
-
-const SHORTCUTS = {
+export const SHORTCUTS = {
   amqp: '@toa.io/bindings.amqp',
   mongodb: '@toa.io/storages.mongodb'
 }
 
-const object = { foo: random(), bar: { baz: generate() } }
-
-exports.object = object
-exports.SHORTCUTS = SHORTCUTS
+export const object = { foo: random(), bar: { baz: generate() } }

package/test/shortcuts.test.js

@@ -1,10 +1,11 @@
-'use strict'
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
 
-const clone = require('clone-deep')
-const { generate } = require('randomstring')
+import clone from 'clone-deep'
+import { generate } from 'randomstring'
 
-const { recognize, resolve } = require('../src/shortcuts')
-const fixtures = require('./shortcuts.fixtures')
+import { recognize, resolve } from '../src/shortcuts.js'
+import * as fixtures from './shortcuts.fixtures.js'
 
 let object
 
@@ -14,16 +15,16 @@ beforeEach(() => {
 
 describe('resolve', () => {
   it('should be defined', () => {
-    expect(resolve).toBeDefined()
+    assert.notStrictEqual(resolve, undefined)
   })
 
   it('should resolve', () => {
-    expect(Object.keys(fixtures.SHORTCUTS).length).toBeGreaterThan(0)
+    assert.ok(Object.keys(fixtures.SHORTCUTS).length > 0)
 
     for (const [key, value] of Object.entries(fixtures.SHORTCUTS)) {
       const resolved = resolve(key)
 
-      expect(resolved).toStrictEqual(value)
+      assert.deepStrictEqual(resolved, value)
     }
   })
 })
@@ -32,7 +33,7 @@ describe('recognize', () => {
   it('should not change unknown', () => {
     recognize(fixtures.SHORTCUTS, object)
 
-    expect(object).toStrictEqual(fixtures.object)
+    assert.deepStrictEqual(object, fixtures.object)
   })
 
   it('should resolve known', () => {
@@ -41,8 +42,8 @@ describe('recognize', () => {
     recognize(fixtures.SHORTCUTS, object)
 
     for (const [alias, name] of Object.entries(fixtures.SHORTCUTS)) {
-      expect(object[alias]).toBeUndefined()
-      expect(object[name]).toStrictEqual(known[name])
+      assert.strictEqual(object[alias], undefined)
+      assert.deepStrictEqual(object[name], known[name])
     }
   })
 
@@ -52,9 +53,10 @@ describe('recognize', () => {
 
     recognize(fixtures.SHORTCUTS, object, group)
 
-    expect(object[group]).toStrictEqual(known)
+    assert.deepStrictEqual(object[group], known)
 
-    for (const alias of Object.keys(fixtures.SHORTCUTS)) expect(object[alias]).toBeUndefined()
+    for (const alias of Object.keys(fixtures.SHORTCUTS))
+      assert.strictEqual(object[alias], undefined)
   })
 
   it('should not overwrite group', () => {
@@ -67,7 +69,7 @@ describe('recognize', () => {
 
     recognize(fixtures.SHORTCUTS, object, group)
 
-    expect(object[group]).toStrictEqual(expect.objectContaining(existing))
+    assert.partialDeepStrictEqual(object[group], existing)
   })
 
   it('should not create empty group', () => {
@@ -75,7 +77,7 @@ describe('recognize', () => {
 
     recognize(object, group)
 
-    expect(object[group]).toBeUndefined()
+    assert.strictEqual(object[group], undefined)
   })
 
   const append = () => {

package/types/component.d.ts

@@ -1,4 +1,5 @@
-import type { Locator, operations } from '@toa.io/core'
+import type { Locator } from '@toa.io/core'
+import type { operations } from '@toa.io/core/types'
 
 type Map = {
   [id: string]: Component
@@ -8,10 +9,13 @@ export type Operation = {
   type: operations.type
   scope?: operations.scope
   bindings?: string[]
+  description?: string
   input?: any
   output?: any
   error?: any
   query?: boolean
+  /** served by every process under an address of its own, which a call to it names */
+  stateful?: boolean
 }
 
 export type Operations = Record<string, Operation>
@@ -34,10 +38,22 @@ type Receiver = {
   source?: string
 }
 
-type Entity = {
-  schema: Object
+type Migration = {
+  id: string
+  steps: unknown[]
+  /** the prototype it is inherited from; absent on the component's own */
+  prototype?: string
+}
+
+export type Entity = {
+  properties: Record<string, Object>
+  required?: string[]
+  /** what a record holds before anything is written to it */
+  blank?: Record<string, unknown>
   storage?: string
-  dependent?: boolean
+  associated?: boolean
+  custom?: boolean
+  migrations?: Migration[]
 }
 
 type Declaration = {
@@ -51,10 +67,13 @@ type Declaration = {
   events?: Events
   receivers?: Record<string, Receiver>
   extensions?: Record<string, object>
-  properties?: Record<string, object>
 }
 
 export type Manifest = Declaration & {
   locator: Locator
   path: string
+  /** what a deploy installs beside this component for what it declares, by package name */
+  packages?: Record<string, string>
+  /** Toa deploys nothing for it: the context evicts it, or only evicted components require it */
+  evicted?: boolean
 }

package/types/context/declaration.d.ts

@@ -1,8 +1,36 @@
-import { Composition, Registry, Runtime } from '../context'
+import { Registry, Runtime } from '../context.js'
 
+/** A composition as declared, before its members are resolved. */
 interface Composition {
-  name: string,
+  name: string
   components: string[]
+  services?: string[]
+}
+
+/** What Toa does not deploy for a context, whatever else names it: still part of it, deployed by other means. */
+export interface Evicted {
+  components?: string[]
+  services?: string[]
+}
+
+export interface Resources {
+  cpu?: [string, string]
+  memory?: [string, string]
+}
+
+export interface Mono {
+  replicas?: number
+  resources?: Resources
+}
+
+/**
+ * Cluster-level ingress configuration, applied to every service that declares one.
+ */
+export interface Ingress {
+  hosts?: string[]
+  class?: string
+  annotations?: Record<string, string>
+  default?: boolean
 }
 
 export interface Declaration {
@@ -11,7 +39,9 @@ export interface Declaration {
   version?: string
   runtime?: Runtime | string
   registry?: Registry | string
-  packages?: string
   compositions?: Composition[]
+  evicted?: Evicted
+  mono?: Mono
+  ingress?: Ingress
   annotations?: Record<string, object>
 }

package/types/context.d.ts

@@ -1,41 +1,47 @@
-import { Manifest } from './component'
+import { Manifest } from './component.js'
 import { Locator } from '@toa.io/core'
-import type { Declaration } from './context/declaration'
+import type { Declaration } from './context/declaration.js'
 
-interface Runtime{
+interface Runtime {
   version: string
   registry?: string
   proxy?: string
 }
 
-interface Registry{
+interface Registry {
   base?: string
   platforms?: string[] | null
+  services?: 'build' | 'published'
   build?: {
     arguments?: string[]
     run?: string
-  },
+  }
   credentials: string
 }
 
-interface Composition{
-  name: string,
-  components: _component.Component[]
+interface Composition {
+  name: string
+  components: Manifest[]
+  services?: string[]
+  /** what a deploy installs for the services this composition runs, by package name */
+  packages?: Record<string, string>
 }
 
-export interface Dependency<T = undefined>{
+export interface Dependency<T = undefined> {
   locator: Locator
-  manifest: T,
+  manifest: T
   component: Manifest
 }
 
-interface Context extends Declaration{
+interface Context extends Declaration {
   runtime?: Runtime
   environment?: string
   registry?: Registry
   compositions?: Composition[]
-  components?: _component.Component[]
+  components?: Manifest[]
   dependencies?: Record<string, Dependency[]>
+  /** what a deploy installs for every service, which is what `mono` runs */
+  packages?: Record<string, string>
 }
 
-export function context (path: string, environment?: string): Promise<Context>
+export function context(path: string, environment?: string): Promise<Context>

package/types/entity.d.ts

@@ -0,0 +1,7 @@
+import type { Entity } from './component.js'
+
+/** The schema a stored record must fit. */
+export function schema(entity: Entity): object
+
+/** The schema a changeset must fit: the same properties, none of them required. */
+export function changeset(entity: Entity): object

package/types/index.d.ts

@@ -1,4 +1,13 @@
-export * as context from './context'
-export * as component from './component'
+export * as context from './context.js'
+export * as component from './component.js'
 
-export { Manifest } from './component'
+export { Manifest } from './component.js'
+export * as entity from './entity.js'
+
+export interface Definition {
+  /** The package's name, or the reference where it has no package.json */
+  name: string
+  module: Record<string, any>
+}
+
+export function definition(reference: string): Promise<Definition>

package/src/.component/.expand/properties.js

@@ -1,14 +0,0 @@
-'use strict'
-
-const { recognize } = require('../../shortcuts')
-
-function properties (manifest) {
-  recognize(SHORTCUTS, manifest, 'properties')
-  recognize(SHORTCUTS, manifest.properties)
-}
-
-const SHORTCUTS = {
-  queues: '@toa.io/storages.queues'
-}
-
-exports.properties = properties

package/src/.context/.dependencies/load.js

@@ -1,36 +0,0 @@
-'use strict'
-
-const { join } = require('node:path')
-
-/**
- * @param {string} path
- * @returns {{ metadata: object, module: object }}
- */
-function load (path) {
-  const metadata = loadMetadata(path)
-  const module = loadModule(path)
-
-  return { metadata, module }
-}
-
-function loadMetadata (reference) {
-  reference = join(reference, 'package.json')
-
-  try {
-    return require(reference)
-  } catch {
-    return null
-  }
-}
-
-/**
- * @param {string} reference
- * @returns {object}
- */
-function loadModule (reference) {
-  const path = require.resolve(reference)
-
-  return require(path)
-}
-
-exports.load = load

package/test/context/dependencies.load.test.js

@@ -1,24 +0,0 @@
-'use strict'
-
-const { join } = require('node:path')
-const { load } = require('../../src/.context/.dependencies/load')
-
-it('should be', async () => {
-  expect(load).toBeInstanceOf(Function)
-})
-
-it('should load module', async () => {
-  const path = join(__dirname, '../../')
-  const { metadata, module } = load(path)
-
-  expect(metadata.name).toStrictEqual('@toa.io/norm')
-  expect(module.context).toBeInstanceOf(Function)
-})
-
-it('should return null metadata if no package.json', async () => {
-  const path = join(__dirname, '../../src')
-  const { metadata, module } = load(path)
-
-  expect(metadata).toBeNull()
-  expect(module.context).toBeInstanceOf(Function)
-})