@specbook/core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The runner, mock engine, template engine and shared proxy behind Specbook: Storybook for APIs.",
   "keywords": [
     "specbook",
@@ -49,6 +49,17 @@
   "dependencies": {
     "uvu": "0.5.6"
   },
+  "peerDependencies": {
+    "@faker-js/faker": "^9.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@faker-js/faker": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@faker-js/faker": "9.3.0"
+  },
   "files": [
     "src",
     "!**/*.test.*"

package/src/config.ts

@@ -1,4 +1,4 @@
-import type { FakerConfig } from './faker'
+import type { FakerConfig } from './faker-runtime'
 import type { AuthProfile } from './runner/run'
 import type { SecretProvider, SecretRef } from './secrets'
 

package/src/faker-runtime.ts

@@ -0,0 +1,88 @@
+// Locale-aware faker proxy. `@faker-js/faker` is a peer dependency of the user's project;
+// the runtime (CLI / UI) installs the concrete instance for the selected locale before a run.
+
+type FakerLike = Record<string, any>
+
+// Held on globalThis so the CLI's bundled copy of core and the project's own import share one instance.
+const KEY = '__specbookFaker'
+const store = globalThis as unknown as Record<string, FakerLike | undefined>
+
+export const faker: FakerLike = new Proxy({} as FakerLike, {
+  get(_t, key) {
+    const current = store[KEY]
+    if (!current) {
+      throw new Error(
+        'faker is not initialised. Install "@faker-js/faker" in your project; specbook sets it up before each run.',
+      )
+    }
+    return current[key as string]
+  },
+})
+
+export function setFaker(instance: FakerLike | undefined): void {
+  store[KEY] = instance
+}
+
+export interface FakerConfig {
+  /** locale name -> fallback chain of faker locale export names, e.g. { de: ['de', 'en', 'base'] } */
+  locales?: Record<string, string[]>
+  default?: string
+}
+
+interface FakerModule {
+  Faker: new (opts: { locale: unknown[] }) => FakerLike
+  [locale: string]: unknown
+}
+
+/** The locale exports a run needs, in fallback order: the chain for `locale`, then `base`. */
+export function fakerLocaleNames(config: FakerConfig = {}, locale?: string): string[] {
+  const name = locale ?? config.default ?? 'en'
+  return [...new Set([...(config.locales?.[name] ?? [name, 'en']), 'base'])]
+}
+
+/** Every locale export a project can reach: the default's chain and each configured locale's, plus `en` and `base`. */
+export function fakerLocaleExports(config: FakerConfig = {}): string[] {
+  const names = new Set<string>(['en', ...fakerLocaleNames(config)])
+  for (const name of Object.keys(config.locales ?? {}))
+    for (const n of fakerLocaleNames(config, name)) names.add(n)
+  return [...names].sort()
+}
+
+/**
+ * The module `installFaker` needs. A bundled build offers each locale as `locales[name]()` so only
+ * the ones a run falls back through are fetched; a plain faker module already has them all.
+ */
+export async function prepareFaker(
+  mod: Record<string, any>,
+  config: FakerConfig = {},
+  locale?: string,
+): Promise<FakerModule> {
+  const locales = mod.locales as Record<string, () => Promise<unknown>> | undefined
+  if (!locales) return mod as FakerModule
+  const ready: Record<string, unknown> = { Faker: mod.Faker }
+  await Promise.all(
+    fakerLocaleNames(config, locale).map(async (n) => {
+      const load = locales[n]
+      if (load) ready[n] = await load()
+    }),
+  )
+  return ready as FakerModule
+}
+
+/** Build a Faker for `locale` from the (dynamically imported) module, install it, and optionally seed it. */
+export function installFaker(
+  mod: FakerModule,
+  config: FakerConfig = {},
+  opts: { locale?: string; seed?: number } = {},
+): FakerLike {
+  const name = opts.locale ?? config.default ?? 'en'
+  const locales = fakerLocaleNames(config, name).map((n) => {
+    const l = mod[n]
+    if (!l) throw new Error(`Unknown faker locale "${n}" (from "${name}")`)
+    return l
+  })
+  const instance = new mod.Faker({ locale: locales })
+  if (opts.seed !== undefined) instance.seed(opts.seed)
+  setFaker(instance)
+  return instance
+}

package/src/faker.ts

@@ -1,80 +1,8 @@
-// Locale-aware faker proxy. `@faker-js/faker` is a peer dependency of the user's project;
-// the runtime (CLI / UI) installs the concrete instance for the selected locale before a run.
+// The `faker` request and flow files import (`@specbook/core/faker`), typed as faker's own `Faker` so a typo or a
+// wrong argument fails `tsc` and the editor completes. `@faker-js/faker` is the project's dependency (`specbook init` adds it);
+// the runtime in ./faker-runtime installs the real instance before each run.
 
-type FakerLike = Record<string, any>
+import type { Faker } from '@faker-js/faker'
+import { faker as runtime } from './faker-runtime'
 
-// Held on globalThis so the CLI's bundled copy of core and the project's own import share one instance.
-const KEY = '__specbookFaker'
-const store = globalThis as unknown as Record<string, FakerLike | undefined>
-
-export const faker: FakerLike = new Proxy({} as FakerLike, {
-  get(_t, key) {
-    const current = store[KEY]
-    if (!current) {
-      throw new Error(
-        'faker is not initialised. Install "@faker-js/faker" in your project; specbook sets it up before each run.',
-      )
-    }
-    return current[key as string]
-  },
-})
-
-export function setFaker(instance: FakerLike | undefined): void {
-  store[KEY] = instance
-}
-
-export interface FakerConfig {
-  /** locale name -> fallback chain of faker locale export names, e.g. { de: ['de', 'en', 'base'] } */
-  locales?: Record<string, string[]>
-  default?: string
-}
-
-interface FakerModule {
-  Faker: new (opts: { locale: unknown[] }) => FakerLike
-  [locale: string]: unknown
-}
-
-/** The locale exports a run needs, in fallback order: the chain for `locale`, then `base`. */
-export function fakerLocaleNames(config: FakerConfig = {}, locale?: string): string[] {
-  const name = locale ?? config.default ?? 'en'
-  return [...new Set([...(config.locales?.[name] ?? [name, 'en']), 'base'])]
-}
-
-/**
- * The module `installFaker` needs. A bundled build offers each locale as `locales[name]()` so only
- * the ones a run falls back through are fetched; a plain faker module already has them all.
- */
-export async function prepareFaker(
-  mod: Record<string, any>,
-  config: FakerConfig = {},
-  locale?: string,
-): Promise<FakerModule> {
-  const locales = mod.locales as Record<string, () => Promise<unknown>> | undefined
-  if (!locales) return mod as FakerModule
-  const ready: Record<string, unknown> = { Faker: mod.Faker }
-  await Promise.all(
-    fakerLocaleNames(config, locale).map(async (n) => {
-      const load = locales[n]
-      if (load) ready[n] = await load()
-    }),
-  )
-  return ready as FakerModule
-}
-
-/** Build a Faker for `locale` from the (dynamically imported) module, install it, and optionally seed it. */
-export function installFaker(
-  mod: FakerModule,
-  config: FakerConfig = {},
-  opts: { locale?: string; seed?: number } = {},
-): FakerLike {
-  const name = opts.locale ?? config.default ?? 'en'
-  const locales = fakerLocaleNames(config, name).map((n) => {
-    const l = mod[n]
-    if (!l) throw new Error(`Unknown faker locale "${n}" (from "${name}")`)
-    return l
-  })
-  const instance = new mod.Faker({ locale: locales })
-  if (opts.seed !== undefined) instance.seed(opts.seed)
-  setFaker(instance)
-  return instance
-}
+export const faker = runtime as unknown as Faker

package/src/index.ts

@@ -5,8 +5,15 @@ export * from './diff'
 export * from './environment'
 export type { Example, ExampleLoader, FileReader, Row } from './example'
 export { fromFormRows, fromRows, toFormRows, toRows } from './example'
-export type { FakerConfig } from './faker'
-export { faker, fakerLocaleNames, installFaker, prepareFaker, setFaker } from './faker'
+export type { FakerConfig } from './faker-runtime'
+export {
+  faker,
+  fakerLocaleExports,
+  fakerLocaleNames,
+  installFaker,
+  prepareFaker,
+  setFaker,
+} from './faker-runtime'
 export * from './mock'
 export * from './oauth'
 export * from './proxy/index'
@@ -31,8 +38,10 @@ export {
 export {
   collectPlaceholders,
   deepMerge,
+  FakerPlaceholderError,
   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

@@ -1,9 +1,14 @@
 // Template engine: `{{ name }}` placeholders, variable lookup only (no expressions).
 
-import { faker } from './faker'
+import { faker } from './faker-runtime'
 
-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
@@ -22,16 +27,30 @@ export function isDeferred(name: string): boolean {
 
 export const isFakerName = (name: string) => name.startsWith('faker.')
 
+/** A `{{faker.…}}` that names no generator, or is not written as a bare `faker.<module>.<method>`. */
+export class FakerPlaceholderError extends TemplateError {
+  constructor(
+    variable: string,
+    override readonly message: string,
+  ) {
+    super(variable)
+    this.name = 'FakerPlaceholderError'
+  }
+}
+
 /** `faker.person.firstName` calls the generator on the active faker instance, fresh on every render. */
 function fromFaker(path: string): { found: boolean; value?: unknown } {
-  let parent: any = faker
-  let cur: any = faker
-  for (const part of path.split('.').slice(1)) {
-    parent = cur
-    cur = cur?.[part]
-    if (cur === undefined) return { found: false }
-  }
-  return { found: true, value: typeof cur === 'function' ? cur.call(parent) : cur }
+  const [, group, method, ...rest] = path.split('.')
+  const unknown = () =>
+    new FakerPlaceholderError(
+      path,
+      `Unknown faker generator "{{${path}}}": use faker.<module>.<method>`,
+    )
+  if (!group || !method || rest.length > 0) throw unknown()
+  const mod = (faker as Record<string, any>)[group]
+  const fn = typeof mod === 'object' && mod !== null ? mod[method] : undefined
+  if (typeof fn !== 'function' || method === 'constructor') throw unknown()
+  return { found: true, value: fn.call(mod) }
 }
 
 /** True when any placeholder in `value` needs the faker instance. */
@@ -39,11 +58,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 }
@@ -52,7 +75,21 @@ function lookup(scope: Record<string, unknown>, path: string): { found: boolean;
   return { found: true, value: cur }
 }
 
+/** `{{faker.number.int(5)}}` does not read as a placeholder: refuse it rather than send it as it is. */
+function rejectFakerCall(s: string): void {
+  if (!s.includes('faker')) return
+  const left = /\{\{\s*(faker\.[\s\S]*?)(?:\}\}|$)/.exec(s.replace(EMBED, ''))
+  if (left) {
+    const name = (left[1] as string).trim()
+    throw new FakerPlaceholderError(
+      name,
+      `"{{${name}}}" is not a faker placeholder: placeholders take no arguments. Use faker in a request file for those.`,
+    )
+  }
+}
+
 export function renderString(s: string, scope: Record<string, unknown>): unknown {
+  rejectFakerCall(s)
   const whole = WHOLE.exec(s)
   if (whole) {
     const name = whole[1] as string