@specbook/core 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/core",
-  "version": "0.4.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,6 +38,7 @@ export {
 export {
   collectPlaceholders,
   deepMerge,
+  FakerPlaceholderError,
   render,
   renderString,
   rootName,

package/src/template.ts

@@ -1,6 +1,6 @@
 // Template engine: `{{ name }}` placeholders, variable lookup only (no expressions).
 
-import { faker } from './faker'
+import { faker } from './faker-runtime'
 
 // 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.$\[\]-]+`
@@ -27,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. */
@@ -61,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