@ghostry/fabricator-extension-faker-v10 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,77 @@
1
+ import type { Faker } from "@faker-js/faker";
2
+ import type { registry } from "@ghostry/fabricator";
3
+ import type { Primitive } from "@ghostry/fabricator/internal";
4
+ import type { FakerModules } from "./FakerModules/Types";
5
+ /**
6
+ * What the mirror needs from whichever registry it is merged into — a
7
+ * structural requirement, not `typeof registry` itself, so an already-extended
8
+ * registry still satisfies it.
9
+ */
10
+ export type Registry = Pick<typeof registry, "array" | "bigint" | "boolean" | "date" | "enum" | "number" | "object" | "opaque" | "string" | "tuple">;
11
+ /**
12
+ * Every module the mirror covers, intersected with `keyof Faker` so every
13
+ * downstream `Faker[$M]` indexing is sound. `FakerModules/Types.ts` is the
14
+ * source of truth — `helpers` is absent from it deliberately (deviation policy
15
+ * in `CLAUDE.md`'s "The faker extension"), so this type excludes it without
16
+ * saying so twice.
17
+ *
18
+ * `test/index.types.test.ts`'s `_ModulesExhaustive` holds this to faker's own
19
+ * module list, naming each exclusion, so a module added upstream fails `check`
20
+ * rather than going quietly unmirrored.
21
+ */
22
+ export type ModuleName = keyof FakerModules & keyof Faker;
23
+ /**
24
+ * A module's method names, read off the declared surface rather than `keyof
25
+ * Faker[$M]`, so this stays correct if the mirror ever stops covering a module
26
+ * exhaustively. It does today — `test/index.types.test.ts`'s
27
+ * `MethodsExhaustive<$M>` asserts the two are equal per module — but that is an
28
+ * assertion about the surface, not a property of this type.
29
+ */
30
+ export type MethodName<$M extends ModuleName> = keyof FakerModules[$M] & keyof Faker[$M];
31
+ /**
32
+ * The `faker` namespace on an extended registry: every module the mirror covers
33
+ * — with `color` additionally carrying the 7 split text/channels nodes
34
+ * alongside its 4 ordinary ones — plus the `use` escape hatch.
35
+ *
36
+ * The module half is `FakerModules/Types.ts`, a hand-maintained _literal_ type
37
+ * rather than a mapped type over the builders. Performance, not style: a mapped
38
+ * type must instantiate every member to resolve any one of them, so having the
39
+ * derived form in the program exhausted TypeScript 5's 5,000,000-instantiation
40
+ * budget and made every `toTypeBox(...)` call fail with TS2589. See that file's
41
+ * header. This repo's `check` runs TypeScript 7, whose budget is larger — `bun
42
+ * run check` passing is _not_ evidence a derived form would be affordable for
43
+ * consumers. `check:ts5` is.
44
+ *
45
+ * Both halves are object-literal types, never `interface`s: only a literal gets
46
+ * an implicit index signature, and `DeepMerge`'s `$AV extends PlainObject` test
47
+ * fails without one, silently degrading `registry.extend` from merging into a
48
+ * node to replacing it wholesale. `test/Mergeable.test.ts` is the guard.
49
+ *
50
+ * `use` is not a faker module name — `test/index.types.test.ts` asserts it
51
+ * never becomes one, since it shares a key space with {@link ModuleName}.
52
+ */
53
+ export type FakerExtension = FakerModules & {
54
+ /**
55
+ * Escape hatch — a plain-object namespace, not a callable, for the
56
+ * `deepMerge` reason above: every form is named, including the untyped one.
57
+ * Each hands the shared, stream-backed `Faker` to a callback, so the call
58
+ * keeps its own inference and still draws from the leaf's seeded stream — the
59
+ * callback runs inside the same producer every ordinary builder runs inside
60
+ * (`src/index.ts`'s `draw`).
61
+ *
62
+ * How `helpers` is reached (omitted from the mirror — deviation policy in
63
+ * `CLAUDE.md`'s "The faker extension"). Kind-tagged forms (`.string`,
64
+ * `.number`, `.date`, `.boolean`, `.bigint`) keep adapter compatibility
65
+ * available there too. `.opaque` is the **only** way to get an `opaque`
66
+ * schema out of this package — honest, since it is the one place the caller
67
+ * has told us nothing about the shape.
68
+ */
69
+ readonly use: {
70
+ readonly string: (produce: (faker: Faker) => string) => Primitive.string.Schema;
71
+ readonly number: (produce: (faker: Faker) => number) => Primitive.number.Schema;
72
+ readonly date: (produce: (faker: Faker) => Date) => Primitive.date.Schema;
73
+ readonly boolean: (produce: (faker: Faker) => boolean) => Primitive.boolean.Schema;
74
+ readonly bigint: (produce: (faker: Faker) => bigint) => Primitive.bigint.Schema;
75
+ readonly opaque: <$T>(produce: (faker: Faker) => $T) => Primitive.opaque.Schema<$T>;
76
+ };
77
+ };
@@ -0,0 +1,82 @@
1
+ import type { LocaleDefinition, Randomizer } from "@faker-js/faker";
2
+ import { Faker } from "@faker-js/faker";
3
+ import type { FakerExtension, Registry } from "./Types";
4
+ export { FakerExtensionError } from "./Error";
5
+ export type { FakerExtension as FakerTypes } from "./Types";
6
+ /**
7
+ * The mirror's type-level machinery — not needed to _use_ it, but exported so a
8
+ * consumer (or this package's compile-time checks in
9
+ * `test/index.types.test.ts`) can name a module or method without a relative
10
+ * `./Types` path tests otherwise avoid (`CLAUDE.md`: tests resolve through the
11
+ * package specifier, exercising built `dist/`).
12
+ *
13
+ * `FakerModules` is the surface those checks are made _against_ — every
14
+ * builder's declared parameters and return Schema — so `Honest<...>` reads the
15
+ * shipped contract, not an intermediate description.
16
+ */
17
+ export type { FakerModules } from "./FakerModules/Types";
18
+ export type { MethodName, ModuleName } from "./Types";
19
+ /**
20
+ * Faker's configuration bag — re-exported so `Options.config` doesn't need
21
+ * `@faker-js/faker` as a direct dependency just to name the type.
22
+ */
23
+ export type FakerConfig = ConstructorParameters<typeof Faker>[0]["config"];
24
+ /**
25
+ * No reference-date option. `Faker`'s `defaultRefDate` is wired to the active
26
+ * fabrication's `clock` (below), so a second independently-configured clock
27
+ * would be a second source of truth free to drift from `T.date.past` in the
28
+ * same schema.
29
+ *
30
+ * No `seed` option and no pre-built `Faker`: a pre-built instance's randomizer
31
+ * is fixed at construction, and accepting one would either ignore it silently
32
+ * or let it compete with fabricator's seed. `create` is the honest escape: the
33
+ * caller builds the instance; it still receives this bridge's `randomizer`, so
34
+ * reproducibility survives.
35
+ */
36
+ export type Options = {
37
+ locale: LocaleDefinition | LocaleDefinition[];
38
+ config?: FakerConfig | undefined;
39
+ create?: never;
40
+ } | {
41
+ create: (randomizer: Randomizer) => Faker;
42
+ locale?: never;
43
+ config?: never;
44
+ };
45
+ /**
46
+ * Returns a `registry.extend` callback rather than the namespace itself, so
47
+ * faker's builders arrive as `T.faker.*` on an ordinary extended registry — the
48
+ * same path any user-defined type uses, and what gives every builder access to
49
+ * the core kinds it wraps:
50
+ *
51
+ * ```ts
52
+ * const { T, Fabricator } = initialize({
53
+ * types: registry.extend(fakerExtension({ locale: en })),
54
+ * });
55
+ *
56
+ * T.object({ name: T.faker.person.fullName() });
57
+ * ```
58
+ *
59
+ * The `Faker` instance is built here, once per `fakerExtension(...)` call, not
60
+ * per `extend` — so a configuration error (an empty `locale`) surfaces at the
61
+ * call the caller wrote, not inside the registry machinery.
62
+ *
63
+ * `FakerExtension` (`./Types.ts`) is spelled out explicitly rather than
64
+ * inferred. An inferred type would reach into each kind's `Schema` interface —
65
+ * internal to `@ghostry/fabricator`, unreachable from its `.` export — and
66
+ * declaration emission (`tsgo`, not `tsc --noEmit`; see `CLAUDE.md`'s
67
+ * declaration-emit trap) refuses to print an anonymous expansion of one. Even
68
+ * where it printed it would be the wrong contract: inference would surface each
69
+ * builder's incidental narrowness (`Schema<{ produce; hints }>`) where the
70
+ * declared surface states `Primitive.string.Schema`.
71
+ *
72
+ * Every node is a plain object or a leaf builder function, never a function
73
+ * carrying properties: `deepMerge` recurses only where `isPlainObject` holds on
74
+ * both sides, so a callable-with-properties silently swallows any later
75
+ * `.extend()` aimed into it. `Construct.ts` upholds this at runtime;
76
+ * `Types.ts`'s `FakerExtension` is the type-level mirror.
77
+ */
78
+ export declare function fakerExtension(options: Options): (params: {
79
+ T: Registry;
80
+ }) => {
81
+ faker: FakerExtension;
82
+ };
package/package.json ADDED
@@ -0,0 +1,63 @@
1
+ {
2
+ "name": "@ghostry/fabricator-extension-faker-v10",
3
+ "version": "0.0.1",
4
+ "license": "MIT",
5
+ "description": "@faker-js/faker integration for @ghostry/fabricator — faker's data generators, seeded and reproducible through the fabricator instance that calls them.",
6
+ "keywords": [
7
+ "factory",
8
+ "faker",
9
+ "extension"
10
+ ],
11
+ "author": {
12
+ "name": "Patrick Rebsch"
13
+ },
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/ghostry-dev/fabricator",
17
+ "directory": "pkg/fabricator-extension-faker-v10"
18
+ },
19
+ "homepage": "https://github.com/ghostry-dev/fabricator",
20
+ "bugs": "https://github.com/ghostry-dev/fabricator/issues",
21
+ "type": "module",
22
+ "types": "./dist/types/index.d.ts",
23
+ "module": "./dist/esm/index.js",
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/types/index.d.ts",
27
+ "import": "./dist/esm/index.js",
28
+ "default": "./dist/esm/index.js"
29
+ }
30
+ },
31
+ "publishConfig": {
32
+ "access": "public",
33
+ "provenance": true
34
+ },
35
+ "scripts": {
36
+ "build:reset": "rm -rf ./dist",
37
+ "build:compile": "bunx --no-install --bun rslib build --config ./rslib.config.ts",
38
+ "build:compile:rsdoctor": "RSDOCTOR=true bunx --no-install --bun rslib build --config ./rslib.config.ts",
39
+ "build:types": "bun --bun ../../node_modules/typescript-5/lib/tsc.js -p ./tsconfig.build.json --noEmit false --declaration --emitDeclarationOnly --declarationDir ./dist/types",
40
+ "build:verify": "tsc --noEmit -p ./tsconfig.verify.json",
41
+ "build:clean": "find ./dist -type f -name '*.tsbuildinfo' -delete",
42
+ "build": "bun run build:reset && bun run build:compile && bun run build:types && bun run build:verify && bun run build:clean",
43
+ "build:rsdoctor": "bun run build:reset && bun run build:compile:rsdoctor && bun run build:types && bun run build:verify && bun run build:clean",
44
+ "check": "tsc --noEmit",
45
+ "check:ts5": "bun --bun ../../node_modules/typescript-5/lib/tsc.js --noEmit",
46
+ "check:jsr": "DENO_BIN_PATH=$PWD/../../node_modules/.bin/deno bunx --no-install jsr publish --dry-run --allow-dirty",
47
+ "format": "bunx --no-install oxfmt .",
48
+ "test": "bun run check && bun run check:ts5 && bun run check:jsr && bun test"
49
+ },
50
+ "files": [
51
+ "dist"
52
+ ],
53
+ "peerDependencies": {
54
+ "@ghostry/fabricator": ">=0.0.1 <0.1.0",
55
+ "@faker-js/faker": "^10.5.0"
56
+ },
57
+ "devDependencies": {
58
+ "@ghostry/fabricator": "0.0.1",
59
+ "@ghostry/fabricator-adapter-typebox-v0": "0.0.1",
60
+ "@faker-js/faker": "^10.5.0",
61
+ "@sinclair/typebox": "^0.34.52"
62
+ }
63
+ }