@pro-laico/payload-seed 0.0.0

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+import type { CollectionSlug, DataFromGlobalSlug, GlobalSlug, RequiredDataFromCollectionSlug } from 'payload';
+import type { file, FileToken, ref, Ref } from './refs';
+/**
+ * Recursively widens a generated Payload data type so a {@link Ref} may appear at any object
+ * field or array element — that's how relationship values are supplied as tokens instead of ids.
+ * The shape (field names, required-ness) is still enforced, so changing a collection's schema still
+ * surfaces a TS error in its seed file. Files aren't widened in here — they go on the record's
+ * `_file` meta-key, not in a data field. Intentionally permissive at the leaf for v1: the runtime
+ * validator checks that each ref actually lands in a field whose config allows it.
+ */
+export type WithRefs<T> = T extends Ref ? T : T extends Date ? T : T extends (infer U)[] ? Array<WithRefs<U> | Ref> : T extends object ? {
+    [K in keyof T]: WithRefs<T[K]> | Ref;
+} : T;
+/** A single collection seed record: the collection's create-data, a local `_key` reference
+ *  handle, and an optional `_file` attaching a source file (for upload / provider collections). */
+export type CollectionSeedData<TSlug extends CollectionSlug> = WithRefs<RequiredDataFromCollectionSlug<TSlug>> & {
+    _key: string;
+    _file?: FileToken;
+};
+/** A global's seed data (globals are singletons — no `_key`). The generated global type
+ *  carries `id`/`globalType`/timestamps that `updateGlobal` doesn't accept as input, so
+ *  they're stripped here. */
+export type GlobalSeedData<TSlug extends GlobalSlug> = WithRefs<Omit<DataFromGlobalSlug<TSlug>, 'id' | 'globalType' | 'createdAt' | 'updatedAt'>>;
+/** Tokens handed to every seed builder: `ref` (point at another seeded doc) and `file`
+ *  (attach a source file to an upload/provider doc via its `_file`). */
+export interface SeedTokens {
+    ref: typeof ref;
+    file: typeof file;
+}
+/**
+ * A collection's `custom.seedAsset` marker: declares a collection whose `_file` bytes are ingested
+ * by the collection's own hook rather than stored as a Payload upload — e.g. `@pro-laico/payload-mux`'s
+ * `mux-video` (uploaded to Mux). Set on the collection config:
+ *
+ *   { slug: 'mux-video', custom: { seedAsset: { sourceField: 'source' } }, ... }
+ *
+ * Instead of uploading bytes, the seed engine resolves the `_file` under `subdir` and sets it as
+ * `{ file, ...options }` on the doc's `sourceField`, for the collection's ingest hook to consume.
+ * `true` is shorthand for the defaults (`sourceField: 'source'`, `subdir`: the collection slug).
+ * Plain config — no import of the seed package needed, so the owning plugin stays decoupled from it.
+ */
+export type SeedAssetMarker = true | {
+    /** Doc field the engine sets to `{ file, ...options }` for the ingest hook. @default 'source' */
+    sourceField?: string;
+    /** Subdirectory under the assets dir holding the source files. @default the collection slug */
+    subdir?: string;
+};
+/**
+ * A collection's `custom.seedDisabled` marker: declares that the collection cannot be seeded right
+ * now (typically missing credentials), set by the owning plugin from its own config/env:
+ *
+ *   { slug: 'mux-video', custom: { seedDisabled: 'Mux credentials not set (MUX_TOKEN_ID / MUX_TOKEN_SECRET)' } }
+ *
+ * The engine skips the collection's definition at runtime with a warning (a string is used as the
+ * reason) and drops any optional field whose `ref()` points at it — a required ref is a hard error.
+ * Because the definition stays registered, the generated seed-ref types don't change with the
+ * environment; set the env vars and the next run seeds it, nothing else to touch. Plain config —
+ * no import of the seed package needed, so the owning plugin stays decoupled from it.
+ */
+export type SeedDisabledMarker = boolean | string;
+/** A seed builder receives the ref/file tokens and returns the seed data. Deferred
+ *  (not eager data) so refs resolve against the full definition set. */
+export type SeedBuilder<T> = (tokens: SeedTokens) => T;
+export interface CollectionSeedDefinition<TSlug extends CollectionSlug = CollectionSlug> {
+    readonly kind: 'collection';
+    readonly slug: TSlug;
+    readonly build: SeedBuilder<Array<CollectionSeedData<TSlug>>>;
+    /** Skip this definition at seed time (a string is used as the warning's reason). The definition
+     *  still contributes to the generated seed-ref types, so gating it doesn't shift types. Also set
+     *  automatically when the target collection declares `custom.seedDisabled`. */
+    readonly disabled?: SeedDisabledMarker;
+}
+export interface GlobalSeedDefinition<TSlug extends GlobalSlug = GlobalSlug> {
+    readonly kind: 'global';
+    readonly slug: TSlug;
+    readonly build: SeedBuilder<GlobalSeedData<TSlug>>;
+    /** Skip this definition at seed time (a string is used as the warning's reason). */
+    readonly disabled?: SeedDisabledMarker;
+}
+export type SeedDefinition = CollectionSeedDefinition | GlobalSeedDefinition;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,8BAA8B,EAAE,MAAM,SAAS,CAAA;AAC7G,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,GACnC,CAAC,GACD,CAAC,SAAS,IAAI,GACZ,CAAC,GACD,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GACnB,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GACxB,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG;CAAE,GACxC,CAAC,CAAA;AAEX;mGACmG;AACnG,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,cAAc,IAAI,QAAQ,CAAC,8BAA8B,CAAC,KAAK,CAAC,CAAC,GAAG;IAC/G,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED;;6BAE6B;AAC7B,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,UAAU,IAAI,QAAQ,CAC7D,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC,CACjF,CAAA;AAED;wEACwE;AACxE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,OAAO,GAAG,CAAA;IACf,IAAI,EAAE,OAAO,IAAI,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GACvB,IAAI,GACJ;IACE,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAEL;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAA;AAEjD;wEACwE;AACxE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,KAAK,CAAC,CAAA;AAEtD,MAAM,WAAW,wBAAwB,CAAC,KAAK,SAAS,cAAc,GAAG,cAAc;IACrF,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC7D;;mFAE+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CACvC;AAED,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU;IACzE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IAClD,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CACvC;AAED,MAAM,MAAM,cAAc,GAAG,wBAAwB,GAAG,oBAAoB,CAAA"}

package/dist/types.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, DataFromGlobalSlug, GlobalSlug, RequiredDataFromCollectionSlug } from 'payload'\nimport type { file, FileToken, ref, Ref } from './refs'\n\n/**\n * Recursively widens a generated Payload data type so a {@link Ref} may appear at any object\n * field or array element — that's how relationship values are supplied as tokens instead of ids.\n * The shape (field names, required-ness) is still enforced, so changing a collection's schema still\n * surfaces a TS error in its seed file. Files aren't widened in here — they go on the record's\n * `_file` meta-key, not in a data field. Intentionally permissive at the leaf for v1: the runtime\n * validator checks that each ref actually lands in a field whose config allows it.\n */\nexport type WithRefs<T> = T extends Ref\n  ? T\n  : T extends Date\n    ? T\n    : T extends (infer U)[]\n      ? Array<WithRefs<U> | Ref>\n      : T extends object\n        ? { [K in keyof T]: WithRefs<T[K]> | Ref }\n        : T\n\n/** A single collection seed record: the collection's create-data, a local `_key` reference\n *  handle, and an optional `_file` attaching a source file (for upload / provider collections). */\nexport type CollectionSeedData<TSlug extends CollectionSlug> = WithRefs<RequiredDataFromCollectionSlug<TSlug>> & {\n  _key: string\n  _file?: FileToken\n}\n\n/** A global's seed data (globals are singletons — no `_key`). The generated global type\n *  carries `id`/`globalType`/timestamps that `updateGlobal` doesn't accept as input, so\n *  they're stripped here. */\nexport type GlobalSeedData<TSlug extends GlobalSlug> = WithRefs<\n  Omit<DataFromGlobalSlug<TSlug>, 'id' | 'globalType' | 'createdAt' | 'updatedAt'>\n>\n\n/** Tokens handed to every seed builder: `ref` (point at another seeded doc) and `file`\n *  (attach a source file to an upload/provider doc via its `_file`). */\nexport interface SeedTokens {\n  ref: typeof ref\n  file: typeof file\n}\n\n/**\n * A collection's `custom.seedAsset` marker: declares a collection whose `_file` bytes are ingested\n * by the collection's own hook rather than stored as a Payload upload — e.g. `@pro-laico/payload-mux`'s\n * `mux-video` (uploaded to Mux). Set on the collection config:\n *\n *   { slug: 'mux-video', custom: { seedAsset: { sourceField: 'source' } }, ... }\n *\n * Instead of uploading bytes, the seed engine resolves the `_file` under `subdir` and sets it as\n * `{ file, ...options }` on the doc's `sourceField`, for the collection's ingest hook to consume.\n * `true` is shorthand for the defaults (`sourceField: 'source'`, `subdir`: the collection slug).\n * Plain config — no import of the seed package needed, so the owning plugin stays decoupled from it.\n */\nexport type SeedAssetMarker =\n  | true\n  | {\n      /** Doc field the engine sets to `{ file, ...options }` for the ingest hook. @default 'source' */\n      sourceField?: string\n      /** Subdirectory under the assets dir holding the source files. @default the collection slug */\n      subdir?: string\n    }\n\n/**\n * A collection's `custom.seedDisabled` marker: declares that the collection cannot be seeded right\n * now (typically missing credentials), set by the owning plugin from its own config/env:\n *\n *   { slug: 'mux-video', custom: { seedDisabled: 'Mux credentials not set (MUX_TOKEN_ID / MUX_TOKEN_SECRET)' } }\n *\n * The engine skips the collection's definition at runtime with a warning (a string is used as the\n * reason) and drops any optional field whose `ref()` points at it — a required ref is a hard error.\n * Because the definition stays registered, the generated seed-ref types don't change with the\n * environment; set the env vars and the next run seeds it, nothing else to touch. Plain config —\n * no import of the seed package needed, so the owning plugin stays decoupled from it.\n */\nexport type SeedDisabledMarker = boolean | string\n\n/** A seed builder receives the ref/file tokens and returns the seed data. Deferred\n *  (not eager data) so refs resolve against the full definition set. */\nexport type SeedBuilder<T> = (tokens: SeedTokens) => T\n\nexport interface CollectionSeedDefinition<TSlug extends CollectionSlug = CollectionSlug> {\n  readonly kind: 'collection'\n  readonly slug: TSlug\n  readonly build: SeedBuilder<Array<CollectionSeedData<TSlug>>>\n  /** Skip this definition at seed time (a string is used as the warning's reason). The definition\n   *  still contributes to the generated seed-ref types, so gating it doesn't shift types. Also set\n   *  automatically when the target collection declares `custom.seedDisabled`. */\n  readonly disabled?: SeedDisabledMarker\n}\n\nexport interface GlobalSeedDefinition<TSlug extends GlobalSlug = GlobalSlug> {\n  readonly kind: 'global'\n  readonly slug: TSlug\n  readonly build: SeedBuilder<GlobalSeedData<TSlug>>\n  /** Skip this definition at seed time (a string is used as the warning's reason). */\n  readonly disabled?: SeedDisabledMarker\n}\n\nexport type SeedDefinition = CollectionSeedDefinition | GlobalSeedDefinition\n"],"names":[],"mappings":"AAmGA,WAA4E"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@pro-laico/payload-seed",
+  "version": "0.0.0",
+  "description": "Schema-aware, type-safe seeding plugin for Payload CMS: typed cross-file references with dependency tracking, robust media uploads, a POST /api/seed endpoint, and a SeedRegistry injected into payload-types.ts.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pro-laico/payload-plugins.git",
+    "directory": "packages/payload-seed"
+  },
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "plugin",
+    "seed",
+    "seeding",
+    "fixtures"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./components/SeedButton": {
+      "types": "./dist/components/SeedButton.d.ts",
+      "import": "./dist/components/SeedButton.js",
+      "default": "./dist/components/SeedButton.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@payloadcms/ui": "^3.0.0",
+    "payload": "^3.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@payloadcms/ui": "^3.85.1",
+    "@types/node": "^26.0.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "payload": "^3.85.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "pnpm clean && pnpm build:types && pnpm build:swc",
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:swc": "swc ./src -d ./dist --config-file ../../.swcrc --strip-leading-paths",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --noCheck"
+  }
+}