@payload-cc/payload-collection-cli 1.0.9 → 1.2.0

package/README.md

@@ -13,14 +13,23 @@ pnpm add @payload-cc/payload-collection-cli
 
 ## Quick Start
 
-You can immediately start using the commands without any configuration!
+You can immediately start using the commands without any configuration for basic insertions/updates!
 
+**Command Syntax**:
+```bash
+npx @payload-cc/payload-collection-cli [-c config-file] <collection-slug> <operation> <file or string>
+```
+
+**Examples**:
 ```bash
 # Bulk create/upsert from jsonlines
 npx @payload-cc/payload-collection-cli posts upsert data.jsonl
 
 # Simple JSON update
 npx @payload-cc/payload-collection-cli users update '{"email": "user@example.com", "name": "New Name"}'
+
+# With explicit mapping configuration
+npx @payload-cc/payload-collection-cli -c ./my-map.config.ts users upsert data.jsonl
 ```
 
 ## Available Actions
@@ -29,10 +38,18 @@ npx @payload-cc/payload-collection-cli users update '{"email": "user@example.com
 - `delete`: Delete records.
 - `upsert`: Update if existing, create if not.
 
+## Specifications & FAQ
+For detailed behavior specifications (such as how identifier lookups work strictly during upserts, updates, and deletes), please refer to the [Specifications & FAQ](docs/references/specs_detail.md).
+
 ## Configuration (Optional)
 
 ### Relation Mappings (`payload-collection-cli.config.ts`)
-If you want the CLI to magically resolve relation IDs (e.g. searching a User by email to relate to a Post), create a `payload-collection-cli.config.ts` in your Payload project root:
+By default, Payload relations require you to provide target document IDs (e.g., ObjectIDs or numeric IDs). The CLI can magically resolve these relations by searching for human-readable fields instead.
+
+**Example Scenario**:
+Assume your `posts` collection has a relationship field named `author` that references the `users` collection. Instead of manually finding and hard-coding the user's database ID, you want to simply provide their email address.
+
+Create a `payload-collection-cli.config.ts` in your Payload project root (or pass it via `-c`) to define the `lookupField` for the `users` collection:
 
 ```typescript
 export const cliConfig = {
@@ -48,7 +65,7 @@ export const cliConfig = {
 }
 ```
 
-Now, when you supply an `author: "user@example.com"` property to a `posts` collection insertion, the CLI will look up the user by email in the exact database rather than forcing you to hard-code Payload ObjectId strings!
+Now, when you supply an `author: "user@example.com"` property to a `posts` collection insertion, the CLI will intercept this relationship, look up the `users` collection by the `email` field, and automatically replace the email string with the actual database ID before inserting!
 
 ## Development & CI/CD
 

package/dist/bin.js

@@ -42,12 +42,20 @@ async function resolveRelations(payload, collectionSlug, data, config) {
   const collection = payload.collections[collectionSlug];
   if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
   const resolved = { ...data };
+  const mappingConfig = config.mappings[collectionSlug];
+  if (mappingConfig?.defaults) {
+    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
+      if (resolved[k] === void 0 || resolved[k] === null) {
+        resolved[k] = v;
+      }
+    }
+  }
   for (const field of collection.config.fields) {
-    if (field.type === "relationship" && data[field.name]) {
+    if (field.type === "relationship" && resolved[field.name]) {
       const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
       const mapping = config.mappings[relationTo];
       if (!mapping) continue;
-      const rawValue = data[field.name];
+      const rawValue = resolved[field.name];
       const isArray = Array.isArray(rawValue);
       const values = isArray ? rawValue : [rawValue];
       const resolvedIds = [];
@@ -60,6 +68,12 @@ async function resolveRelations(payload, collectionSlug, data, config) {
           });
           if (found.docs.length > 0) {
             resolvedIds.push(found.docs[0].id);
+          } else if (mapping.onNotFound === "create") {
+            const created = await payload.create({
+              collection: relationTo,
+              data: { [mapping.lookupField]: val }
+            });
+            resolvedIds.push(created.id);
           } else if (mapping.onNotFound === "error") {
             throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
           } else {
@@ -84,24 +98,34 @@ async function processSingle(payload, collection, action, data, config) {
     case "create":
       return await payload.create({ collection, data: resolved });
     case "upsert":
-      const existing = await payload.find({
+      if (data[lookupField] === void 0) {
+        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
+      }
+      const existingUpsert = await payload.find({
         collection,
         where: { [lookupField]: { equals: data[lookupField] } }
       });
-      if (existing.docs.length > 0) {
-        return await payload.update({ collection, id: existing.docs[0].id, data: resolved });
+      if (existingUpsert.docs.length > 0) {
+        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
       }
       return await payload.create({ collection, data: resolved });
     case "update":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
+      }
       return await payload.update({
         collection,
         where: { [lookupField]: { equals: data[lookupField] } },
         data: resolved
       });
     case "delete":
+      const delVal = typeof data === "object" ? data[lookupField] : data;
+      if (delVal === void 0) {
+        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
+      }
       return await payload.delete({
         collection,
-        where: { [lookupField]: { equals: typeof data === "object" ? data[lookupField] : data } }
+        where: { [lookupField]: { equals: delVal } }
       });
     default:
       throw new Error(`Unsupported action: ${action}`);
@@ -122,10 +146,38 @@ async function execute(payload, collection, action, input, config) {
 // src/bin.ts
 var jiti = (0, import_jiti.createJiti)(importMetaUrl);
 async function run() {
-  const [collection, action, input] = process.argv.slice(2);
+  const args = process.argv.slice(2);
+  let configOptIdx = args.indexOf("-c");
+  if (configOptIdx === -1) configOptIdx = args.indexOf("--config");
+  let cliConfig = { mappings: {} };
+  if (configOptIdx !== -1) {
+    if (args.length <= configOptIdx + 1) {
+      console.error("\u274C Error: Missing option after --config parameter.");
+      process.exit(1);
+    }
+    const val = args[configOptIdx + 1];
+    args.splice(configOptIdx, 2);
+    if (val.trim().startsWith("{")) {
+      try {
+        cliConfig = JSON.parse(val);
+      } catch (err) {
+        console.error("\u274C Error: Failed to parse inline JSON config:", err);
+        process.exit(1);
+      }
+    } else {
+      const customConfigPath = import_path2.default.resolve(process.cwd(), val);
+      if (!require("fs").existsSync(customConfigPath)) {
+        console.error(`\u274C Error: Config file not found at ${customConfigPath}`);
+        process.exit(1);
+      }
+      const imported = await jiti.import(customConfigPath);
+      cliConfig = imported.cliConfig || imported.default || cliConfig;
+    }
+  }
+  const [collection, action, input] = args;
   const root = process.cwd();
   if (!collection || !action || !input) {
-    console.log("Usage: payload-collection-cli <collection> <action> <json|file.jsonl>");
+    console.log("Usage: payload-collection-cli [-c path] <collection> <action> <json|file.jsonl>");
     process.exit(1);
   }
   const configPath = [
@@ -134,12 +186,6 @@ async function run() {
   ].find((p) => require("fs").existsSync(p));
   if (!configPath) throw new Error("payload.config.ts not found.");
   const { default: payloadConfig } = await jiti.import(configPath);
-  let cliConfig = { mappings: {} };
-  const cliCfgPath = import_path2.default.resolve(root, "payload-collection-cli.config.ts");
-  if (require("fs").existsSync(cliCfgPath)) {
-    const imported = await jiti.import(cliCfgPath);
-    cliConfig = imported.cliConfig || imported.default || cliConfig;
-  }
   const payload = await (0, import_payload.getPayload)({ config: payloadConfig });
   try {
     const result = await execute(payload, collection, action, input, cliConfig);

package/dist/bin.mjs

@@ -2,7 +2,7 @@
 import {
   __require,
   execute
-} from "./chunk-3HKWP2RE.mjs";
+} from "./chunk-RIXWYITK.mjs";
 
 // src/bin.ts
 import { getPayload } from "payload";
@@ -10,10 +10,38 @@ import { createJiti } from "jiti";
 import path from "path";
 var jiti = createJiti(import.meta.url);
 async function run() {
-  const [collection, action, input] = process.argv.slice(2);
+  const args = process.argv.slice(2);
+  let configOptIdx = args.indexOf("-c");
+  if (configOptIdx === -1) configOptIdx = args.indexOf("--config");
+  let cliConfig = { mappings: {} };
+  if (configOptIdx !== -1) {
+    if (args.length <= configOptIdx + 1) {
+      console.error("\u274C Error: Missing option after --config parameter.");
+      process.exit(1);
+    }
+    const val = args[configOptIdx + 1];
+    args.splice(configOptIdx, 2);
+    if (val.trim().startsWith("{")) {
+      try {
+        cliConfig = JSON.parse(val);
+      } catch (err) {
+        console.error("\u274C Error: Failed to parse inline JSON config:", err);
+        process.exit(1);
+      }
+    } else {
+      const customConfigPath = path.resolve(process.cwd(), val);
+      if (!__require("fs").existsSync(customConfigPath)) {
+        console.error(`\u274C Error: Config file not found at ${customConfigPath}`);
+        process.exit(1);
+      }
+      const imported = await jiti.import(customConfigPath);
+      cliConfig = imported.cliConfig || imported.default || cliConfig;
+    }
+  }
+  const [collection, action, input] = args;
   const root = process.cwd();
   if (!collection || !action || !input) {
-    console.log("Usage: payload-collection-cli <collection> <action> <json|file.jsonl>");
+    console.log("Usage: payload-collection-cli [-c path] <collection> <action> <json|file.jsonl>");
     process.exit(1);
   }
   const configPath = [
@@ -22,12 +50,6 @@ async function run() {
   ].find((p) => __require("fs").existsSync(p));
   if (!configPath) throw new Error("payload.config.ts not found.");
   const { default: payloadConfig } = await jiti.import(configPath);
-  let cliConfig = { mappings: {} };
-  const cliCfgPath = path.resolve(root, "payload-collection-cli.config.ts");
-  if (__require("fs").existsSync(cliCfgPath)) {
-    const imported = await jiti.import(cliCfgPath);
-    cliConfig = imported.cliConfig || imported.default || cliConfig;
-  }
   const payload = await getPayload({ config: payloadConfig });
   try {
     const result = await execute(payload, collection, action, input, cliConfig);

package/dist/{chunk-3HKWP2RE.mjs → chunk-RIXWYITK.mjs}

@@ -10,12 +10,20 @@ async function resolveRelations(payload, collectionSlug, data, config) {
   const collection = payload.collections[collectionSlug];
   if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
   const resolved = { ...data };
+  const mappingConfig = config.mappings[collectionSlug];
+  if (mappingConfig?.defaults) {
+    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
+      if (resolved[k] === void 0 || resolved[k] === null) {
+        resolved[k] = v;
+      }
+    }
+  }
   for (const field of collection.config.fields) {
-    if (field.type === "relationship" && data[field.name]) {
+    if (field.type === "relationship" && resolved[field.name]) {
       const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
       const mapping = config.mappings[relationTo];
       if (!mapping) continue;
-      const rawValue = data[field.name];
+      const rawValue = resolved[field.name];
       const isArray = Array.isArray(rawValue);
       const values = isArray ? rawValue : [rawValue];
       const resolvedIds = [];
@@ -28,6 +36,12 @@ async function resolveRelations(payload, collectionSlug, data, config) {
           });
           if (found.docs.length > 0) {
             resolvedIds.push(found.docs[0].id);
+          } else if (mapping.onNotFound === "create") {
+            const created = await payload.create({
+              collection: relationTo,
+              data: { [mapping.lookupField]: val }
+            });
+            resolvedIds.push(created.id);
           } else if (mapping.onNotFound === "error") {
             throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
           } else {
@@ -55,24 +69,34 @@ async function processSingle(payload, collection, action, data, config) {
     case "create":
       return await payload.create({ collection, data: resolved });
     case "upsert":
-      const existing = await payload.find({
+      if (data[lookupField] === void 0) {
+        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
+      }
+      const existingUpsert = await payload.find({
         collection,
         where: { [lookupField]: { equals: data[lookupField] } }
       });
-      if (existing.docs.length > 0) {
-        return await payload.update({ collection, id: existing.docs[0].id, data: resolved });
+      if (existingUpsert.docs.length > 0) {
+        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
       }
       return await payload.create({ collection, data: resolved });
     case "update":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
+      }
       return await payload.update({
         collection,
         where: { [lookupField]: { equals: data[lookupField] } },
         data: resolved
       });
     case "delete":
+      const delVal = typeof data === "object" ? data[lookupField] : data;
+      if (delVal === void 0) {
+        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
+      }
       return await payload.delete({
         collection,
-        where: { [lookupField]: { equals: typeof data === "object" ? data[lookupField] : data } }
+        where: { [lookupField]: { equals: delVal } }
       });
     default:
       throw new Error(`Unsupported action: ${action}`);

package/dist/index.d.mts

@@ -4,6 +4,7 @@ import { Payload } from 'payload';
 interface MappingConfig {
     lookupField: string;
     onNotFound?: 'error' | 'ignore' | 'create';
+    defaults?: Record<string, any>;
 }
 interface CLIConfig {
     mappings: Record<string, MappingConfig>;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Payload } from 'payload';
 interface MappingConfig {
     lookupField: string;
     onNotFound?: 'error' | 'ignore' | 'create';
+    defaults?: Record<string, any>;
 }
 interface CLIConfig {
     mappings: Record<string, MappingConfig>;

package/dist/index.js

@@ -40,12 +40,20 @@ async function resolveRelations(payload, collectionSlug, data, config) {
   const collection = payload.collections[collectionSlug];
   if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
   const resolved = { ...data };
+  const mappingConfig = config.mappings[collectionSlug];
+  if (mappingConfig?.defaults) {
+    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
+      if (resolved[k] === void 0 || resolved[k] === null) {
+        resolved[k] = v;
+      }
+    }
+  }
   for (const field of collection.config.fields) {
-    if (field.type === "relationship" && data[field.name]) {
+    if (field.type === "relationship" && resolved[field.name]) {
       const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
       const mapping = config.mappings[relationTo];
       if (!mapping) continue;
-      const rawValue = data[field.name];
+      const rawValue = resolved[field.name];
       const isArray = Array.isArray(rawValue);
       const values = isArray ? rawValue : [rawValue];
       const resolvedIds = [];
@@ -58,6 +66,12 @@ async function resolveRelations(payload, collectionSlug, data, config) {
           });
           if (found.docs.length > 0) {
             resolvedIds.push(found.docs[0].id);
+          } else if (mapping.onNotFound === "create") {
+            const created = await payload.create({
+              collection: relationTo,
+              data: { [mapping.lookupField]: val }
+            });
+            resolvedIds.push(created.id);
           } else if (mapping.onNotFound === "error") {
             throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
           } else {
@@ -85,24 +99,34 @@ async function processSingle(payload, collection, action, data, config) {
     case "create":
       return await payload.create({ collection, data: resolved });
     case "upsert":
-      const existing = await payload.find({
+      if (data[lookupField] === void 0) {
+        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
+      }
+      const existingUpsert = await payload.find({
         collection,
         where: { [lookupField]: { equals: data[lookupField] } }
       });
-      if (existing.docs.length > 0) {
-        return await payload.update({ collection, id: existing.docs[0].id, data: resolved });
+      if (existingUpsert.docs.length > 0) {
+        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
       }
       return await payload.create({ collection, data: resolved });
     case "update":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
+      }
       return await payload.update({
         collection,
         where: { [lookupField]: { equals: data[lookupField] } },
         data: resolved
       });
     case "delete":
+      const delVal = typeof data === "object" ? data[lookupField] : data;
+      if (delVal === void 0) {
+        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
+      }
       return await payload.delete({
         collection,
-        where: { [lookupField]: { equals: typeof data === "object" ? data[lookupField] : data } }
+        where: { [lookupField]: { equals: delVal } }
       });
     default:
       throw new Error(`Unsupported action: ${action}`);

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   execute,
   resolveRelations
-} from "./chunk-3HKWP2RE.mjs";
+} from "./chunk-RIXWYITK.mjs";
 export {
   execute,
   resolveRelations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payload-cc/payload-collection-cli",
-  "version": "1.0.9",
+  "version": "1.2.0",
   "description": "Functional CLI for Payload 3.0 collection management",
   "repository": {
     "type": "git",
@@ -22,7 +22,8 @@
   "scripts": {
     "build": "tsup src/index.ts src/bin.ts --format cjs,esm --dts --clean --shims && chmod +x dist/bin.js",
     "release": "pnpm build && pnpm publish --access public",
-    "test": "vitest run"
+    "test": "vitest run tests/*",
+    "test:e2e": "vitest run e2e-tests/scenarios/ --no-file-parallelism"
   },
   "keywords": [
     "payload",
@@ -40,9 +41,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "next": "^16.2.0",
     "payload": "^3.79.1",
-    "react": "^19.2.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"