@specbook/core 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The runner, mock engine, template engine and shared proxy behind Specbook: Storybook for APIs.",
   "keywords": [
     "specbook",

package/src/index.ts

@@ -33,6 +33,7 @@ export {
   deepMerge,
   render,
   renderString,
+  rootName,
   TemplateError,
   usesFaker,
 } from './template'

package/src/reporters/index.ts

@@ -54,7 +54,7 @@ export interface JUnitOptions {
   hostname?: string
   /** shown as `<properties>` on each suite (env, git sha, seed…) */
   properties?: Record<string, string | undefined>
-  /** service → origin, for the trace in `<system-out>` */
+  /** service → the address its calls go to (origin and base path), for the trace in `<system-out>` */
   origins?: Record<string, string>
 }
 

package/src/reporters/list.ts

@@ -13,7 +13,7 @@ export interface ListOptions {
   quiet?: boolean
   /** show the request and response of a failed step (default), of every step, or not at all */
   trace?: 'on-failure' | 'always' | 'off'
-  /** service → origin, to show full addresses in a trace */
+  /** service → the address its calls go to (origin and base path), so a trace shows the URL that was called */
   origins?: Record<string, string>
   /** paths are shown relative to this folder */
   cwd?: string

package/src/reporters/trace.ts

@@ -16,7 +16,7 @@ const SHOWN_RESPONSE_HEADERS = [
 ]
 
 export interface TraceOptions {
-  /** service → origin (`https://api.example.com`), to show the full address */
+  /** service → the address its calls go to (`https://api.example.com/v1`: origin and base path), to show the full URL */
   origins?: Record<string, string>
   /** characters of a body shown before it is cut (default 2048) */
   maxBody?: number

package/src/runner/run.ts

@@ -11,6 +11,7 @@ import {
   isFakerName,
   isPlainObject,
   render,
+  rootName,
 } from '../template'
 import type {
   ApiResponse,
@@ -201,7 +202,7 @@ function usesOf(
   const out: VarUse[] = []
   for (const name of names) {
     if (isDeferred(name) || isFakerName(name)) continue
-    const key = name.split('.')[0] as string
+    const key = rootName(name)
     if (seen.has(key)) continue
     seen.add(key)
     for (let i = layers.length - 1; i >= 0; i--) {

package/src/runner/transport.ts

@@ -58,6 +58,40 @@ export function absoluteBase(baseUrl: string, pageHref?: string): string {
 /** How long a request waits for an answer when nothing says otherwise. */
 export const DEFAULT_TIMEOUT_MS = 30_000
 
+/** What node's fetch says in `error.cause.code`, in words a person can act on. */
+const WHY: Record<string, string> = {
+  ECONNREFUSED: 'connection refused',
+  ENOTFOUND: 'host not found',
+  EAI_AGAIN: 'host not found',
+  ECONNRESET: 'connection reset',
+  ETIMEDOUT: 'connection timed out',
+  UND_ERR_CONNECT_TIMEOUT: 'connection timed out',
+  EHOSTUNREACH: 'host unreachable',
+  ENETUNREACH: 'network unreachable',
+}
+
+/** node's bare "fetch failed" says nothing; its cause says why. A browser gives no cause, so its error is left as it is. */
+function unreachable(e: unknown, url: string): unknown {
+  const cause = (
+    e as { cause?: { code?: string; message?: string; errors?: { code?: string }[] } } | undefined
+  )?.cause
+  if (!(e instanceof TypeError) || !cause) return e
+  const code = cause.code ?? cause.errors?.find((x) => x.code)?.code
+  const tls =
+    code && /^CERT_|^ERR_TLS|SELF_SIGNED|UNABLE_TO_VERIFY/.test(code) ? 'certificate problem' : ''
+  // a reason there are words for, else the cause's own message ("bad port"), else nothing to add
+  const own = typeof cause.message === 'string' && cause.message.length <= 120 ? cause.message : ''
+  const why = (code && WHY[code]) || tls || own
+  if (!why) return e
+  let host = url
+  try {
+    host = new URL(url).host
+  } catch {
+    /* an address that is not a URL is shown as it is */
+  }
+  return new Error(`Could not reach ${host}: ${why}.`, { cause: e })
+}
+
 export interface FetchTransportOptions {
   baseUrl: (service: string) => string
   fetch?: typeof fetch
@@ -85,8 +119,9 @@ export function createFetchTransport(opts: FetchTransportOptions): Transport {
         }, req.timeoutMs)
       : undefined
     signal?.addEventListener('abort', () => ctl.abort())
+    const url = buildUrl(opts.baseUrl(req.service), req)
     try {
-      const res = await f(buildUrl(opts.baseUrl(req.service), req), {
+      const res = await f(url, {
         method: req.method,
         headers,
         body,
@@ -112,7 +147,7 @@ export function createFetchTransport(opts: FetchTransportOptions): Transport {
       if (timedOut) throw new Error(`Timed out after ${req.timeoutMs}ms: no answer from the API.`)
       // a person pressing Stop, or the run's own deadline: say so, not "This operation was aborted"
       if (signal?.aborted) throw new Error('Stopped before the API answered.')
-      throw e
+      throw unreachable(e, url)
     } finally {
       if (timer) clearTimeout(timer)
     }

package/src/template.ts

@@ -2,8 +2,13 @@
 
 import { faker } from './faker'
 
-const WHOLE = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/
-const EMBED = /\{\{\s*([\w.$-]+)\s*\}\}/g
+// a name is words joined by dots, and a position in an array can be a dot (`tags.0.name`) or brackets (`tags[0].name`)
+const NAME = String.raw`[\w.$\[\]-]+`
+const WHOLE = new RegExp(String.raw`^\s*\{\{\s*(${NAME})\s*\}\}\s*$`)
+const EMBED = new RegExp(String.raw`\{\{\s*(${NAME})\s*\}\}`, 'g')
+
+/** The variable a placeholder starts from: `tags` for `tags[0].name`, `pet` for `pet.category.name`. */
+export const rootName = (name: string): string => name.split(/[.[]/, 1)[0] as string
 
 /** Namespaces resolved at the transport boundary, never in the request model. */
 export const DEFERRED_NAMESPACES = ['secrets', 'session'] as const
@@ -39,11 +44,15 @@ export function usesFaker(value: unknown): boolean {
   return [...collectPlaceholders(value)].some(isFakerName)
 }
 
+/** `tags[0].name` is `tags.0.name`: a position in brackets is the same step as one after a dot. */
+const steps = (path: string) => path.replace(/\[(\d+)\]/g, '.$1').split('.')
+
 function lookup(scope: Record<string, unknown>, path: string): { found: boolean; value?: unknown } {
   if (isFakerName(path)) return fromFaker(path)
   let cur: unknown = scope
-  for (const part of path.split('.')) {
-    if (cur !== null && typeof cur === 'object' && part in (cur as object)) {
+  for (const part of steps(path)) {
+    // a value's own properties only: `toString` and `constructor` are not data, so a placeholder cannot reach them
+    if (cur !== null && typeof cur === 'object' && Object.hasOwn(cur as object, part)) {
       cur = (cur as Record<string, unknown>)[part]
     } else {
       return { found: false }