@toa.io/extensions.exposition 1.0.0-alpha.284 → 1.0.0-alpha.286

package/source/RPC/names.test.ts

@@ -7,65 +7,79 @@ import { address, name, refusal } from './names.js'
 
 describe('address', () => {
   it('should resolve a name without variables', () => {
-    assert.deepEqual(address('pots/GET', {}),
-      { path: '/pots/', verb: 'GET', variables: [] })
+    assert.deepEqual(address('pots.GET', {}), {
+      path: '/pots/',
+      verb: 'GET',
+      variables: []
+    })
   })
 
   it('should resolve the trunk', () => {
-    assert.deepEqual(address('GET', {}),
-      { path: '/', verb: 'GET', variables: [] })
+    assert.deepEqual(address('GET', {}), { path: '/', verb: 'GET', variables: [] })
   })
 
   it('should substitute a variable and report it taken', () => {
-    assert.deepEqual(address('pots/_id/GET', { id: 'a1b2', title: 'Kettle' }),
-      { path: '/pots/a1b2/', verb: 'GET', variables: ['id'] })
+    assert.deepEqual(address('pots._id.GET', { id: 'a1b2', title: 'Kettle' }), {
+      path: '/pots/a1b2/',
+      verb: 'GET',
+      variables: ['id']
+    })
   })
 
   it('should substitute every variable', () => {
-    assert.deepEqual(address('users/_user/pots/_id/PATCH', { user: 'bob', id: 'a1b2' }),
-      { path: '/users/bob/pots/a1b2/', verb: 'PATCH', variables: ['user', 'id'] })
+    assert.deepEqual(address('users._user.pots._id.PATCH', { user: 'bob', id: 'a1b2' }), {
+      path: '/users/bob/pots/a1b2/',
+      verb: 'PATCH',
+      variables: ['user', 'id']
+    })
   })
 
   it('should let a tail carry separators', () => {
-    assert.deepEqual(address('files/__/GET', { '**': 'a/b/c' }),
-      { path: '/files/a/b/c/', verb: 'GET', variables: ['**'] })
+    assert.deepEqual(address('files.__.GET', { '**': 'a/b/c' }), {
+      path: '/files/a/b/c/',
+      verb: 'GET',
+      variables: ['**']
+    })
   })
 
   it('should not confuse a trailing literal with a verb', () => {
-    assert.deepEqual(address('pots/GET/POST', {}),
-      { path: '/pots/GET/', verb: 'POST', variables: [] })
+    assert.deepEqual(address('pots.GET.POST', {}), {
+      path: '/pots/GET/',
+      verb: 'POST',
+      variables: []
+    })
   })
 
   it('should refuse a name that states no verb', () => {
-    assert.throws(() => address('pots/_id', { id: 'a1b2' }), http.NotFound)
+    assert.throws(() => address('pots._id', { id: 'a1b2' }), http.NotFound)
   })
 
   it('should refuse a verb no method uses', () => {
-    assert.throws(() => address('pots/FETCH', {}), http.NotFound)
+    assert.throws(() => address('pots.FETCH', {}), http.NotFound)
   })
 
   it('should refuse a segment no name can spell', () => {
-    assert.throws(() => address('pots/v1.0/GET', {}), http.NotFound)
-    assert.throws(() => address('a_b/GET', {}), http.NotFound)
-    assert.throws(() => address('pots//GET', {}), http.NotFound)
+    assert.throws(() => address('pots/v1.GET', {}), http.NotFound)
+    assert.throws(() => address('a_b.GET', {}), http.NotFound)
+    assert.throws(() => address('pots..GET', {}), http.NotFound)
   })
 
   it('should refuse a variable of no name', () => {
-    assert.throws(() => address('pots/_/GET', { '': 'a1b2' }), http.NotFound)
+    assert.throws(() => address('pots._.GET', { '': 'a1b2' }), http.NotFound)
   })
 
   it('should refuse a missing variable', () => {
-    assert.throws(() => address('pots/_id/GET', {}), http.BadRequest)
+    assert.throws(() => address('pots._id.GET', {}), http.BadRequest)
   })
 
   it('should refuse a variable that would divide the path', () => {
-    assert.throws(() => address('pots/_id/GET', { id: 'a/b' }), http.BadRequest)
-    assert.throws(() => address('pots/_id/GET', { id: 'a?b' }), http.BadRequest)
-    assert.throws(() => address('pots/_id/GET', { id: 'a#b' }), http.BadRequest)
+    assert.throws(() => address('pots._id.GET', { id: 'a/b' }), http.BadRequest)
+    assert.throws(() => address('pots._id.GET', { id: 'a?b' }), http.BadRequest)
+    assert.throws(() => address('pots._id.GET', { id: 'a#b' }), http.BadRequest)
   })
 
   it('should refuse a tail that would end the path', () => {
-    assert.throws(() => address('files/__/GET', { '**': 'a?b' }), http.BadRequest)
+    assert.throws(() => address('files.__.GET', { '**': 'a?b' }), http.BadRequest)
   })
 })
 
@@ -75,22 +89,24 @@ describe('name', () => {
   })
 
   it('should name a route', () => {
-    assert.equal(name(segment('/pots'), 'GET'), 'pots/GET')
-    assert.equal(name(segment('/identity/tokens'), 'POST'), 'identity/tokens/POST')
+    assert.equal(name(segment('/pots'), 'GET'), 'pots.GET')
+    assert.equal(name(segment('/identity/tokens'), 'POST'), 'identity.tokens.POST')
   })
 
   it('should mark a variable', () => {
-    assert.equal(name(segment('/pots/:id'), 'GET'), 'pots/_id/GET')
-    assert.equal(name(segment('/identity/tokens/:identity'), 'POST'),
-      'identity/tokens/_identity/POST')
+    assert.equal(name(segment('/pots/:id'), 'GET'), 'pots._id.GET')
+    assert.equal(
+      name(segment('/identity/tokens/:identity'), 'POST'),
+      'identity.tokens._identity.POST'
+    )
   })
 
   it('should mark a tail', () => {
-    assert.equal(name(segment('/files/**'), 'GET'), 'files/__/GET')
+    assert.equal(name(segment('/files/**'), 'GET'), 'files.__.GET')
   })
 
   it('should keep a hyphen', () => {
-    assert.equal(name(segment('/jpeg-or-png'), 'GET'), 'jpeg-or-png/GET')
+    assert.equal(name(segment('/jpeg-or-png'), 'GET'), 'jpeg-or-png.GET')
   })
 
   it('should name nothing where a segment cannot be spelled', () => {
@@ -103,8 +119,11 @@ describe('name', () => {
   it('should round-trip what it names', () => {
     const named = name(segment('/pots/:id'), 'GET')!
 
-    assert.deepEqual(address(named, { id: 'a1b2' }),
-      { path: '/pots/a1b2/', verb: 'GET', variables: ['id'] })
+    assert.deepEqual(address(named, { id: 'a1b2' }), {
+      path: '/pots/a1b2/',
+      verb: 'GET',
+      variables: ['id']
+    })
   })
 })
 

package/source/RPC/names.ts

@@ -7,8 +7,9 @@ import { QUERY, type Params } from './types.js'
  * What a name resolves to: the path the call is made at, and the verb it is made with.
  *
  * A name is the route template with its variables marked and the verb appended as a segment
- * of its own — `pots/_id/GET`. Neither `/` nor a verb can be mistaken for anything else: the
- * verb is always the last segment, and `/` cannot occur inside one.
+ * of its own — `pots._id.GET`. The revision names the characters a tool's name may hold, and
+ * `/` is not among them, so segments are joined by `.` — which a segment cannot hold either,
+ * so nothing in a name can be mistaken for anything else, and the verb is always last.
  */
 export interface Address {
   path: string
@@ -18,12 +19,11 @@ export interface Address {
   variables: string[]
 }
 
-export function address (method: string, params: Params): Address {
+export function address(method: string, params: Params): Address {
   const parts = method.split(SEPARATOR)
   const verb = parts.pop()!
 
-  if (!verbs.has(verb))
-    throw new http.NotFound(`'${method}' names no method`)
+  if (!verbs.has(verb)) throw new http.NotFound(`'${method}' names no method`)
 
   const variables: string[] = []
   const fragments: string[] = []
@@ -65,13 +65,15 @@ export function address (method: string, params: Params): Address {
  * What the call carries, as a request carries it: the path took its variables, `query` is
  * the querystring, and the rest is the body.
  */
-export function split (params: Params, variables: string[]): { query?: Params, input?: Params } {
+export function split(
+  params: Params,
+  variables: string[]
+): { query?: Params; input?: Params } {
   const input: Params = {}
   let query: Params | undefined
 
   for (const [key, value] of Object.entries(params)) {
-    if (variables.includes(key))
-      continue
+    if (variables.includes(key)) continue
 
     if (key !== QUERY) {
       input[key] = value
@@ -90,30 +92,27 @@ export function split (params: Params, variables: string[]): { query?: Params, i
 }
 
 /** The parameter a part reads, or nothing where the part is a literal segment. */
-function parameter (part: string): string | null {
-  if (part === TAIL)
-    return WILDCARD
+function parameter(part: string): string | null {
+  if (part === TAIL) return WILDCARD
 
   return part[0] === VARIABLE ? part.slice(1) : null
 }
 
 /** A segment a name cannot spell is a segment no name has, so this one names nothing. */
-function literal (part: string, method: string): string {
-  if (!NAMEABLE.test(part))
-    throw new http.NotFound(`'${method}' names no procedure`)
+function literal(part: string, method: string): string {
+  if (!NAMEABLE.test(part)) throw new http.NotFound(`'${method}' names no procedure`)
 
   return part
 }
 
 /** The name of a method on this route, or nothing where the route has none. */
-export function name (segments: Segment[], verb: string): string | null {
+export function name(segments: Segment[], verb: string): string | null {
   const parts: string[] = []
 
   for (const segment of segments) {
     const part = component(segment)
 
-    if (part === null)
-      return null
+    if (part === null) return null
 
     parts.push(part)
   }
@@ -124,44 +123,39 @@ export function name (segments: Segment[], verb: string): string | null {
 }
 
 /** The segment that leaves a route unnameable, as it was declared, or nothing where none does. */
-export function refusal (segments: Segment[]): string | null {
+export function refusal(segments: Segment[]): string | null {
   for (const segment of segments)
-    if (component(segment) === null)
-      return declared(segment)
+    if (component(segment) === null) return declared(segment)
 
   return null
 }
 
-function component (segment: Segment): string | null {
+function component(segment: Segment): string | null {
   if (segment.fragment !== null)
     return NAMEABLE.test(segment.fragment) ? segment.fragment : null
 
-  if (segment.wildcard === true)
-    return TAIL
+  if (segment.wildcard === true) return TAIL
 
   // it stands for a segment the caller cannot name, so there is nothing to substitute
-  if (segment.placeholder === null)
-    return null
+  if (segment.placeholder === null) return null
 
   return NAMEABLE.test(segment.placeholder) ? VARIABLE + segment.placeholder : null
 }
 
 /** The route as it was declared, which is how a message about it should read. */
-export function template (segments: Segment[]): string {
+export function template(segments: Segment[]): string {
   return '/' + segments.map(declared).join('/')
 }
 
-function declared (segment: Segment): string {
-  if (segment.fragment !== null)
-    return segment.fragment
+function declared(segment: Segment): string {
+  if (segment.fragment !== null) return segment.fragment
 
-  if (segment.wildcard === true)
-    return '**'
+  if (segment.wildcard === true) return '**'
 
   return segment.placeholder === null ? '*' : ':' + segment.placeholder
 }
 
-const SEPARATOR = '/'
+const SEPARATOR = '.'
 const VARIABLE = '_'
 const TAIL = '__'
 

package/source/RTD/Directives.ts

@@ -3,7 +3,7 @@ import type * as syntax from './syntax/index.js'
 import type { Context, OutgoingMessage, Options } from '../HTTP/index.js'
 import type { Output } from '../io.js'
 import type { Introspection } from '../Introspection.js'
-import type { extensions } from '@toa.io/core'
+import type { extensions } from '@toa.io/core/types'
 
 type Host = extensions.Host
 
@@ -18,7 +18,10 @@ export interface Directives {
   precall: (context: Context, parameters: Parameter[]) => Promise<Output>
 
   /** What this route's directives make of what its method says about itself. */
-  explain: (context: Context, introspection: Introspection) => Promise<Introspection | null>
+  explain: (
+    context: Context,
+    introspection: Introspection
+  ) => Promise<Introspection | null>
   settle: (context: Context, response: OutgoingMessage) => Promise<void>
   dispose: () => void
 }
@@ -71,9 +74,11 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
   preflight?: (request: Context & TExtension) => void | Promise<void>
 
   /** Call-scoped, with what the node declares. Runs once per call. */
-  precall?: (directives: TDirective[],
+  precall?: (
+    directives: TDirective[],
     request: Context & TExtension,
-    parameters: Parameter[]) => Output | Promise<Output>
+    parameters: Parameter[]
+  ) => Output | Promise<Output>
 
   /**
    * What this family's directives make of what the method says about itself, which is
@@ -84,22 +89,28 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
    * is why no parameters are passed — so a directive that can only tell from one hands back
    * what it was given.
    */
-  explain?: (directives: TDirective[],
+  explain?: (
+    directives: TDirective[],
     request: Context & TExtension,
-    introspection: Introspection) => Introspection | null | Promise<Introspection | null>
+    introspection: Introspection
+  ) => Introspection | null | Promise<Introspection | null>
 
   /** Call-scoped, on the message that call produced. */
-  settle?: (directives: TDirective[],
+  settle?: (
+    directives: TDirective[],
     request: Context & TExtension,
-    response: OutgoingMessage) => void | Promise<void>
+    response: OutgoingMessage
+  ) => void | Promise<void>
 
   /**
    * Request-scoped, on the message going back — the counterpart of `preflight`, and
    * likewise without directives. A reply the whole request carries, such as a re-issued
    * credential, is written here rather than by a call that would not own it.
    */
-  depart?: (request: Context & TExtension,
-    response: OutgoingMessage) => void | Promise<void>
+  depart?: (
+    request: Context & TExtension,
+    response: OutgoingMessage
+  ) => void | Promise<void>
 
   dispose?: (directives: TDirective[]) => void
 }

package/source/RTD/Endpoint.ts

@@ -5,7 +5,10 @@ import type * as RTD from './index.js'
 import type { Introspection } from '../Introspection.js'
 
 export interface Endpoint {
-  call: (context: http.Context, parameters: RTD.Parameter[]) => Promise<http.OutgoingMessage>
+  call: (
+    context: http.Context,
+    parameters: RTD.Parameter[]
+  ) => Promise<http.OutgoingMessage>
 
   explain: (parameters: RTD.Parameter[]) => Promise<Introspection>
 

package/source/RTD/Method.ts

@@ -9,7 +9,7 @@ export class Method {
   public readonly endpoint: Endpoint | null
   public readonly directives: Directives
 
-  public constructor (endpoint: Endpoint | null, directives: Directives) {
+  public constructor(endpoint: Endpoint | null, directives: Directives) {
     this.endpoint = endpoint
     this.directives = directives
   }
@@ -19,17 +19,19 @@ export class Method {
    * refuse this caller. A method of no endpoint — one a directive answers on its own —
    * states nothing of its own, and its directives still have their say.
    */
-  public async explain (context: Context, parameters: Parameter[]): Promise<Introspection | null> {
-    const introspection = this.endpoint === null
-      ? {}
-      : await this.endpoint.explain(parameters)
+  public async explain(
+    context: Context,
+    parameters: Parameter[]
+  ): Promise<Introspection | null> {
+    const introspection =
+      this.endpoint === null ? {} : await this.endpoint.explain(parameters)
 
     const described = await this.directives.explain(context, introspection)
 
     return described === null ? null : order(described)
   }
 
-  public async close (): Promise<void> {
+  public async close(): Promise<void> {
     await this.endpoint?.close()
   }
 }

package/source/RTD/Node.ts

@@ -13,7 +13,7 @@ export class Node {
   private readonly protected: boolean
   private routes: Route[]
 
-  public constructor (routes: Route[], methods: Methods, properties: Properties) {
+  public constructor(routes: Route[], methods: Methods, properties: Properties) {
     this.routes = routes
     this.methods = methods
     this.protected = properties.protected
@@ -24,13 +24,16 @@ export class Node {
     this.sort()
   }
 
-  public match (fragments: string[], parameters: Parameter[] = []): Match | null {
+  public match(fragments: string[], parameters: Parameter[] = []): Match | null {
+    // a route only pushes, so what a failed one added is cut off rather than the array copied
+    const mark = parameters.length
+
     for (const route of this.routes) {
-      const params = parameters.slice()
-      const match = route.match(fragments, params)
+      const match = route.match(fragments, parameters)
+
+      if (match !== null) return match
 
-      if (match !== null)
-        return match
+      parameters.length = mark
     }
 
     return null
@@ -40,7 +43,7 @@ export class Node {
    * Returns the nodes the merged branch has landed on, so that its expiration
    * can later be extended without rebuilding anything.
    */
-  public merge (node: Node): Node[] {
+  public merge(node: Node): Node[] {
     this.intermediate = node.intermediate
 
     const nodes = this.protected ? this.append(node) : this.replace(node)
@@ -50,9 +53,8 @@ export class Node {
     return nodes
   }
 
-  public touch (expiration: number): void {
-    if (!this.protected)
-      this.expiration = expiration
+  public touch(expiration: number): void {
+    if (!this.protected) this.expiration = expiration
   }
 
   /**
@@ -62,33 +64,34 @@ export class Node {
    * answers at the same place and is reached instead. The trunk is the exception `match`
    * makes for it — `'/'` answers the trunk itself, whatever it holds.
    */
-  public * walk (segments: Segment[], trunk = false): Generator<Mount> {
+  public *walk(segments: Segment[], trunk = false): Generator<Mount> {
     if (trunk || !this.intermediate)
       for (const [verb, method] of Object.entries(this.methods))
         yield { segments, verb, method }
 
-    for (const route of this.routes)
-      yield * route.walk(segments)
+    for (const route of this.routes) yield* route.walk(segments)
   }
 
   /** Every method of this node that this caller may reach, in the order they were declared. */
-  public async explain (context: Context,
-    parameters: Parameter[]): Promise<Record<string, Introspection>> {
+  public async explain(
+    context: Context,
+    parameters: Parameter[]
+  ): Promise<Record<string, Introspection>> {
     const entries = Object.entries(this.methods)
 
-    const explained = await Promise.all(entries
-      .map(async ([, method]) => await method.explain(context, parameters)))
+    const explained = await Promise.all(
+      entries.map(async ([, method]) => await method.explain(context, parameters))
+    )
 
     const methods: Record<string, Introspection> = {}
 
     for (let i = 0; i < entries.length; i++)
-      if (explained[i] !== null)
-        methods[entries[i][0]] = explained[i]!
+      if (explained[i] !== null) methods[entries[i][0]] = explained[i]!
 
     return methods
   }
 
-  private replace (node: Node): Node[] {
+  private replace(node: Node): Node[] {
     const methods = Object.values(this.methods)
 
     this.routes = node.routes
@@ -97,44 +100,39 @@ export class Node {
     this.forward = node.forward
 
     // race condition is really unlikely
-    for (const method of methods)
-      void method.close()
+    for (const method of methods) void method.close()
 
     return this.nodes()
   }
 
-  private append (node: Node): Node[] {
+  private append(node: Node): Node[] {
     const nodes: Node[] = []
 
-    for (const route of node.routes)
-      nodes.push(...this.route(route))
+    for (const route of node.routes) nodes.push(...this.route(route))
 
-    for (const [verb, method] of Object.entries(node.methods))
-      this.methods[verb] = method
+    for (const [verb, method] of Object.entries(node.methods)) this.methods[verb] = method
 
     return nodes
   }
 
-  private route (candidate: Route): Node[] {
+  private route(candidate: Route): Node[] {
     for (const route of this.routes)
-      if (candidate.equals(route))
-        return route.merge(candidate)
+      if (candidate.equals(route)) return route.merge(candidate)
 
     this.routes.push(candidate)
 
     return candidate.node.nodes()
   }
 
-  private nodes (): Node[] {
+  private nodes(): Node[] {
     const nodes: Node[] = [this]
 
-    for (const route of this.routes)
-      nodes.push(...route.node.nodes())
+    for (const route of this.routes) nodes.push(...route.node.nodes())
 
     return nodes
   }
 
-  private sort (): void {
+  private sort(): void {
     this.routes.sort((a, b) => {
       return a.variables === b.variables
         ? b.segments.length - a.segments.length // routes with more segments should be matched first

package/source/RTD/Route.ts

@@ -9,7 +9,7 @@ export class Route {
   public readonly node: Node
   private readonly wildcard: boolean = false
 
-  public constructor (segments: Segment[], node: Node) {
+  public constructor(segments: Segment[], node: Node) {
     this.root = segments.length === 0
     this.segments = segments
     this.node = node
@@ -21,15 +21,13 @@ export class Route {
       }
   }
 
-  public match (fragments: string[], parameters: Parameter[]): Match | null {
-    if (Date.now() >= this.node.expiration)
-      return null
+  public match(fragments: string[], parameters: Parameter[]): Match | null {
+    if (Date.now() >= this.node.expiration) return null
 
     for (let i = 0; i < this.segments.length; i++) {
       const segment = this.segments[i]
 
-      if (segment.fragment !== null && segment.fragment !== fragments[i])
-        return null
+      if (segment.fragment !== null && segment.fragment !== fragments[i]) return null
 
       if (segment.fragment === null && segment.placeholder !== null)
         parameters.push({ name: segment.placeholder, value: decode(fragments[i]) })
@@ -37,7 +35,10 @@ export class Route {
       if (segment.fragment === null && segment.wildcard === true)
         parameters.push({
           name: '**',
-          value: fragments.slice(this.segments.length - 1).map(decode).join('/')
+          value: fragments
+            .slice(this.segments.length - 1)
+            .map(decode)
+            .join('/')
         })
     }
 
@@ -45,34 +46,30 @@ export class Route {
 
     if ((exact && !this.node.intermediate) || this.wildcard)
       return { node: this.node, parameters }
-    else
-      return this.matchNested(fragments, parameters)
+    else return this.matchNested(fragments, parameters)
   }
 
-  public * walk (prefix: Segment[]): Generator<Mount> {
+  public *walk(prefix: Segment[]): Generator<Mount> {
     // an expired branch is not matched, so nothing under it is reachable to name
-    if (Date.now() >= this.node.expiration)
-      return
+    if (Date.now() >= this.node.expiration) return
 
-    yield * this.node.walk(prefix.concat(this.segments))
+    yield* this.node.walk(prefix.concat(this.segments))
   }
 
-  public equals (route: Route): boolean {
-    if (route.segments.length !== this.segments.length)
-      return false
+  public equals(route: Route): boolean {
+    if (route.segments.length !== this.segments.length) return false
 
     for (let i = 0; i < this.segments.length; i++)
-      if (this.segments[i].fragment !== route.segments[i].fragment)
-        return false
+      if (this.segments[i].fragment !== route.segments[i].fragment) return false
 
     return true
   }
 
-  public merge (route: Route): Node[] {
+  public merge(route: Route): Node[] {
     return this.node.merge(route.node)
   }
 
-  private matchNested (fragments: string[], parameters: Parameter[]): Match | null {
+  private matchNested(fragments: string[], parameters: Parameter[]): Match | null {
     fragments = fragments.slice(this.segments.length)
 
     return this.node.match(fragments, parameters)
@@ -87,7 +84,7 @@ export class Route {
  * An escape that decodes to nothing valid is left as it stands; refusing the route over it
  * would answer `404` to a request whose only fault is its spelling.
  */
-function decode (fragment: string): string {
+function decode(fragment: string): string {
   try {
     return decodeURIComponent(fragment)
   } catch {