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

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 {

package/source/RTD/Tree.ts

@@ -15,7 +15,11 @@ export class Tree {
   private readonly endpoints: EndpointsFactory
   private readonly directives: DirectiveFactory
 
-  public constructor (node: syntax.Node, endpoints: EndpointsFactory, directives: DirectiveFactory) {
+  public constructor(
+    node: syntax.Node,
+    endpoints: EndpointsFactory,
+    directives: DirectiveFactory
+  ) {
     this.endpoints = endpoints
     this.directives = directives
     this.root = node
@@ -24,7 +28,7 @@ export class Tree {
     unnameable(this.trunk)
   }
 
-  public match (path: string): Match | null {
+  public match(path: string): Match | null {
     if (path === '/')
       return {
         node: this.trunk,
@@ -37,11 +41,11 @@ export class Tree {
   }
 
   /** Every method in the tree, with the template it answers at. */
-  public walk (): Generator<Mount> {
+  public walk(): Generator<Mount> {
     return this.trunk.walk([], TRUNK)
   }
 
-  public merge (node: syntax.Node, extension: unknown): Node[] {
+  public merge(node: syntax.Node, extension: unknown): Node[] {
     const branch = this.createNode(node, !PROTECTED, extension)
 
     unnameable(branch)
@@ -53,18 +57,17 @@ export class Tree {
    * Extends the expiration of an already merged branch, leaving its endpoints
    * and their remotes intact.
    */
-  public refresh (nodes: Node[]): void {
+  public refresh(nodes: Node[]): void {
     const expiration = Date.now() + branchTTL()
 
-    for (const node of nodes)
-      node.touch(expiration)
+    for (const node of nodes) node.touch(expiration)
   }
 
-  public dispose (): void {
+  public dispose(): void {
     this.directives.dispose()
   }
 
-  private createNode (node: syntax.Node, protect: boolean, extension?: unknown): Node {
+  private createNode(node: syntax.Node, protect: boolean, extension?: unknown): Node {
     const context: Context = {
       protected: protect,
       endpoints: this.endpoints,
@@ -73,7 +76,7 @@ export class Tree {
         // A merged branch is mounted under the root, so it inherits the root's
         // directives. The trunk is the root: createNode adds them itself, and
         // seeding them here too would apply every one of them twice.
-        stack: node === this.root ? [] : this.root.directives ?? []
+        stack: node === this.root ? [] : (this.root.directives ?? [])
       },
       path: label(extension),
       extension
@@ -87,19 +90,17 @@ export class Tree {
  * What is served but cannot be called by name. Said once per route as it is built, because a
  * procedure that is missing is otherwise noticed only by the caller who cannot find it.
  */
-function unnameable (node: Node): void {
+function unnameable(node: Node): void {
   const said = new Set<string>()
 
   for (const { segments } of node.walk([], TRUNK)) {
     const segment = refusal(segments)
 
-    if (segment === null)
-      continue
+    if (segment === null) continue
 
     const route = template(segments)
 
-    if (said.has(route))
-      continue
+    if (said.has(route)) continue
 
     said.add(route)
 
@@ -112,9 +113,8 @@ function unnameable (node: Node): void {
  * known while it is being built — so the component it came from is what keeps two
  * branches from looking like the same route.
  */
-function label (extension: unknown): string {
-  if (extension === null || typeof extension !== 'object')
-    return ''
+function label(extension: unknown): string {
+  if (extension === null || typeof extension !== 'object') return ''
 
   const { namespace, component } = extension as Record<string, unknown>
 

package/source/RTD/factory.ts

@@ -6,17 +6,14 @@ import { Method, type Methods } from './Method.js'
 import type { Context } from './Context.js'
 import type * as syntax from './syntax/index.js'
 
-export function createNode (node: syntax.Node, context: Context): Node {
-  if (node.isolated === true)
-    context.directives.stack = node.directives
-  else
-    context.directives.stack = node.directives.concat(context.directives.stack)
+export function createNode(node: syntax.Node, context: Context): Node {
+  if (node.isolated === true) context.directives.stack = node.directives
+  else context.directives.stack = node.directives.concat(context.directives.stack)
 
   const routes: Route[] = node.routes.map((route) => createRoute(route, context))
   const methods: Methods = {}
 
-  for (const method of node.methods)
-    methods[method.verb] = createMethod(method, context)
+  for (const method of node.methods) methods[method.verb] = createMethod(method, context)
 
   const protect = node.protected ?? context.protected
 
@@ -29,18 +26,17 @@ export function createNode (node: syntax.Node, context: Context): Node {
   return new Node(routes, methods, properties)
 }
 
-export function branchTTL (): number {
+export function branchTTL(): number {
   const value = process.env.__TESTING_EXPOSITION_BRANCH_TTL
 
-  if (value === undefined || value === '')
-    return BRANCH_TTL
+  if (value === undefined || value === '') return BRANCH_TTL
 
   const parsed = Number(value)
 
   return Number.isFinite(parsed) ? parsed : BRANCH_TTL
 }
 
-function createRoute (route: syntax.Route, context: Context): Route {
+function createRoute(route: syntax.Route, context: Context): Route {
   const stack = context.directives.stack.slice()
   const path = context.path
   const segments = segment(route.path)
@@ -55,18 +51,19 @@ function createRoute (route: syntax.Route, context: Context): Route {
   return new Route(segments, node)
 }
 
-function join (base: string, path: string): string {
+function join(base: string, path: string): string {
   // '/one/' and '/two/' would otherwise read as '/one//two/'
   return (base + path).replace(/\/+/g, '/').replace(/(.)\/$/, '$1')
 }
 
-function createMethod (method: syntax.Method, context: Context): Method {
+function createMethod(method: syntax.Method, context: Context): Method {
   const stack = method.directives.concat(context.directives.stack)
   const directives = context.directives.factory.create(stack, context.path)
 
-  const endpoint = method.mapping?.endpoint === undefined
-    ? null
-    : context.endpoints.create(method, context)
+  const endpoint =
+    method.mapping?.endpoint === undefined
+      ? null
+      : context.endpoints.create(method, context)
 
   return new Method(endpoint, directives)
 }

package/source/RTD/segment.ts

@@ -1,8 +1,8 @@
-export function segment (path: string): Segment[] {
+export function segment(path: string): Segment[] {
   return fragment(path).map(parse)
 }
 
-export function fragment (path: string): string[] {
+export function fragment(path: string): string[] {
   const parts = path.split('/')
 
   // trailing slash
@@ -12,17 +12,19 @@ export function fragment (path: string): string[] {
   return parts.splice(1)
 }
 
-function parse (segment: string): Segment {
+function parse(segment: string): Segment {
   if (segment[0] === ':') return { fragment: null, placeholder: segment.substring(1) }
   else if (segment === '*') return { fragment: null, placeholder: null }
   else if (segment === '**') return { fragment: null, placeholder: null, wildcard: true }
   else return { fragment: segment }
 }
 
-export type Segment = {
-  fragment: string
-} | {
-  fragment: null
-  placeholder: string | null
-  wildcard?: boolean
-}
+export type Segment =
+  | {
+      fragment: string
+    }
+  | {
+      fragment: null
+      placeholder: string | null
+      wildcard?: boolean
+    }

package/source/RTD/syntax/parse.test.ts

@@ -120,7 +120,9 @@ describe('methods', () => {
     const node = parse(declaration)
     const root = node.routes[0].node
 
-    assert.deepStrictEqual(root.methods[0].directives, [{ family: 'auth', name: 'incept', value: 'id' }])
+    assert.deepStrictEqual(root.methods[0].directives, [
+      { family: 'auth', name: 'incept', value: 'id' }
+    ])
   })
 })
 
@@ -132,9 +134,7 @@ describe('directives', () => {
       }
     }
 
-    const shortcuts = new Map<string, string>([
-      ['foo', 'dev:foo']
-    ])
+    const shortcuts = new Map<string, string>([['foo', 'dev:foo']])
 
     const node = parse(declaration, shortcuts)
     const root = node.routes[0].node
@@ -150,7 +150,10 @@ describe('validation', () => {
   it('should throw on unknown key', async () => {
     const declaration = { hello: 'world' }
 
-    assert.throws(() => parse(declaration), (error: any) => /RTD parse error: unknown key 'hello'/.test(error.message))
+    assert.throws(
+      () => parse(declaration),
+      (error: any) => /RTD parse error: unknown key 'hello'/.test(error.message)
+    )
   })
 
   it('should throw on invalid mapping', async () => {
@@ -163,7 +166,10 @@ describe('validation', () => {
       }
     }
 
-    assert.throws(() => parse(declaration), (error: any) => /\/methods\/0\/mapping/.test(error.message))
+    assert.throws(
+      () => parse(declaration),
+      (error: any) => /\/methods\/0\/mapping/.test(error.message)
+    )
   })
 })
 

package/source/RTD/syntax/parse.ts

@@ -9,7 +9,7 @@ import {
   type Range
 } from './types.js'
 
-export function parse (input: object, shortcuts?: Shortcuts): Node {
+export function parse(input: object, shortcuts?: Shortcuts): Node {
   const node = parseNode(input, shortcuts)
 
   schemas.node.validate(node)
@@ -17,7 +17,7 @@ export function parse (input: object, shortcuts?: Shortcuts): Node {
   return node
 }
 
-function parseNode (input: object | string, shortcuts?: Shortcuts): Node {
+function parseNode(input: object | string, shortcuts?: Shortcuts): Node {
   const node = createNode()
 
   if (typeof input === 'string') {
@@ -71,7 +71,7 @@ function parseNode (input: object | string, shortcuts?: Shortcuts): Node {
   return node
 }
 
-export function createNode (): Node {
+export function createNode(): Node {
   return {
     routes: [],
     methods: [],
@@ -79,17 +79,21 @@ export function createNode (): Node {
   }
 }
 
-function parseRoute (path: string, value: Node, shortcuts?: Shortcuts): Route {
+function parseRoute(path: string, value: Node, shortcuts?: Shortcuts): Route {
   const node = parse(value, shortcuts)
 
   return createRoute(path, node)
 }
 
-function createRoute (path: string, node: Node): Route {
+function createRoute(path: string, node: Node): Route {
   return { path, node }
 }
 
-function parseMethod (verb: string, value: Mapping | string, shortcuts?: Shortcuts): Method {
+function parseMethod(
+  verb: string,
+  value: Mapping | string,
+  shortcuts?: Shortcuts
+): Method {
   const mapping = typeof value === 'string' ? { endpoint: value } : value
 
   parseEndpoint(mapping)
@@ -100,9 +104,8 @@ function parseMethod (verb: string, value: Mapping | string, shortcuts?: Shortcu
   return { verb, mapping, directives }
 }
 
-function parseEndpoint (mapping: Mapping): void {
-  if (mapping.endpoint === undefined)
-    return
+function parseEndpoint(mapping: Mapping): void {
+  if (mapping.endpoint === undefined) return
 
   const [endpoiont, component, namespace] = mapping.endpoint.split('.').reverse()
 
@@ -113,27 +116,26 @@ function parseEndpoint (mapping: Mapping): void {
   }
 }
 
-function parseQuery (mapping: any): void {
+function parseQuery(mapping: any): void {
   const query = mapping.query
 
-  if (query === undefined || query === null)
-    return
+  if (query === undefined || query === null) return
 
-  if (typeof query.limit === 'number')
-    query.limit = expandRange(query.limit as number)
+  if (typeof query.limit === 'number') query.limit = expandRange(query.limit as number)
 
-  if (typeof query.omit === 'number')
-    query.omit = expandRange(query.omit as number)
+  if (typeof query.omit === 'number') query.omit = expandRange(query.omit as number)
 }
 
-function parseDirectives (mapping: Record<string, any>, shortcuts?: Shortcuts): Directive[] {
+function parseDirectives(
+  mapping: Record<string, any>,
+  shortcuts?: Shortcuts
+): Directive[] {
   const directives: Directive[] = []
 
   for (const [key, value] of Object.entries(mapping)) {
     const directive = parseDirective(key, value, shortcuts)
 
-    if (directive === null)
-      continue
+    if (directive === null) continue
 
     directives.push(directive)
 
@@ -144,21 +146,23 @@ function parseDirectives (mapping: Record<string, any>, shortcuts?: Shortcuts):
   return directives
 }
 
-function parseDirective (key: string, value: any, shortcuts?: Shortcuts): Directive | null {
-  if (shortcuts?.has(key) === true)
-    key = shortcuts.get(key)! // eslint-disable-line @typescript-eslint/no-non-null-assertion
+function parseDirective(
+  key: string,
+  value: any,
+  shortcuts?: Shortcuts
+): Directive | null {
+  if (shortcuts?.has(key) === true) key = shortcuts.get(key)! // eslint-disable-line @typescript-eslint/no-non-null-assertion
 
   const match = key.match(DIRECTIVE_RX)
 
-  if (match === null)
-    return null
+  if (match === null) return null
 
-  const { family, name } = match.groups as { family: string, name: string }
+  const { family, name } = match.groups as { family: string; name: string }
 
   return { family, name, value }
 }
 
-function expandRange (range: number): Range {
+function expandRange(range: number): Range {
   return { value: range, range: [range, range] }
 }
 

package/source/RTD/syntax/types.ts

@@ -29,6 +29,13 @@ export interface Mapping {
   component?: string
   endpoint: string
   query?: Query | null
+
+  /**
+   * Whether the operation this maps to answers a page of a collection, and so takes the
+   * `omit` and `limit` a page is taken by. Written where the component's manifest is read,
+   * beside `namespace` and `component`, and not declared.
+   */
+  paged?: boolean
 }
 
 export interface Query {
@@ -50,4 +57,13 @@ export interface Range {
   range: [number, number]
 }
 
-export const verbs = new Set<string>(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK'])
+export const verbs = new Set<string>([
+  'GET',
+  'HEAD',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'LOCK',
+  'UNLOCK'
+])

package/source/RTD/walk.test.ts

@@ -18,7 +18,11 @@ const directives = {
   dispose: mock.fn()
 } as unknown as DirectiveFactory
 
-const node = (path: string, verbs: string[] = [], routes: syntax.Route[] = []): syntax.Route => ({
+const node = (
+  path: string,
+  verbs: string[] = [],
+  routes: syntax.Route[] = []
+): syntax.Route => ({
   path,
   node: {
     routes,
@@ -34,8 +38,9 @@ const trunk = (routes: syntax.Route[], verbs: string[] = []): syntax.Node => ({
 })
 
 /** What a walk names, which is what a caller of `/.rpc` would write. */
-function names (tree: Tree): string[] {
-  return [...tree.walk()].map(({ segments, verb }) => name(segments, verb))
+function names(tree: Tree): string[] {
+  return [...tree.walk()]
+    .map(({ segments, verb }) => name(segments, verb))
     .filter((named): named is string => named !== null)
 }
 
@@ -47,51 +52,76 @@ describe('walk', () => {
   })
 
   it('should name every method of every route', () => {
-    const tree = new Tree(trunk([
-      node('/pots', ['GET', 'POST'], [node('/:id', ['GET', 'DELETE'])])
-    ]), endpoints, directives)
+    const tree = new Tree(
+      trunk([node('/pots', ['GET', 'POST'], [node('/:id', ['GET', 'DELETE'])])]),
+      endpoints,
+      directives
+    )
 
     assert.deepEqual(names(tree).sort(), [
-      'pots.GET', 'pots.POST', 'pots._id.DELETE', 'pots._id.GET'
+      'pots.GET',
+      'pots.POST',
+      'pots._id.DELETE',
+      'pots._id.GET'
     ])
   })
 
   it('should walk a branch that was merged', () => {
     const tree = new Tree(trunk([]), endpoints, directives)
 
-    tree.merge(trunk([node('/pots', ['GET'])]), { namespace: 'default', component: 'pots' })
+    tree.merge(trunk([node('/pots', ['GET'])]), {
+      namespace: 'default',
+      component: 'pots'
+    })
 
     assert.deepEqual(names(tree), ['pots.GET'])
   })
 
   it('should name a tail', () => {
-    const tree = new Tree(trunk([node('/files', [], [node('/**', ['GET'])])]),
-      endpoints, directives)
+    const tree = new Tree(
+      trunk([node('/files', [], [node('/**', ['GET'])])]),
+      endpoints,
+      directives
+    )
 
     assert.deepEqual(names(tree), ['files.__.GET'])
   })
 
   it('should skip an intermediate node, whose route answers in its place', () => {
-    const tree = new Tree(trunk([
-      // `/posts` is intermediate: `/posts/` is answered by its `/` route, not by itself
-      node('/posts', ['PATCH'], [node('/', ['PUT'])])
-    ]), endpoints, directives)
+    const tree = new Tree(
+      trunk([
+        // `/posts` is intermediate: `/posts/` is answered by its `/` route, not by itself
+        node('/posts', ['PATCH'], [node('/', ['PUT'])])
+      ]),
+      endpoints,
+      directives
+    )
 
     assert.deepEqual(names(tree), ['posts.PUT'])
   })
 
   it('should name nothing where a segment cannot be spelled', () => {
-    const tree = new Tree(trunk([node('/v1.0', ['GET']), node('/pots', ['GET'])]),
-      endpoints, directives)
+    const tree = new Tree(
+      trunk([node('/v1.0', ['GET']), node('/pots', ['GET'])]),
+      endpoints,
+      directives
+    )
 
     assert.deepEqual(names(tree), ['pots.GET'])
   })
 
   it('should name what the tree then matches', () => {
-    const tree = new Tree(trunk([
-      node('/pots', ['GET'], [node('/:id', ['GET']), node('/hot', ['GET'])]),
-      node('/files', [], [node('/**', ['GET'])])
-    ], ['GET']), endpoints, directives)
+    const tree = new Tree(
+      trunk(
+        [
+          node('/pots', ['GET'], [node('/:id', ['GET']), node('/hot', ['GET'])]),
+          node('/files', [], [node('/**', ['GET'])])
+        ],
+        ['GET']
+      ),
+      endpoints,
+      directives
+    )
 
     const params = { id: 'a1b2', '**': 'a/b/c' }
 
@@ -103,8 +133,15 @@ describe('walk', () => {
       const { path } = address(named!, params)
       const match = tree.match(path)
 
-      assert.notStrictEqual(match, null, `'${named!}' resolves to '${path}', which matches`)
-      assert.ok(verb in match!.node.methods, `'${named!}' matches a node that answers ${verb}`)
+      assert.notStrictEqual(
+        match,
+        null,
+        `'${named!}' resolves to '${path}', which matches`
+      )
+      assert.ok(
+        verb in match!.node.methods,
+        `'${named!}' matches a node that answers ${verb}`
+      )
     }
   })
 })