@davincicoding/payload-utils 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { BasePayload, JsonObject, TypeWithID } from 'payload';
+import z from 'zod';
+export declare const documentIdSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+export type DocumentID = TypeWithID['id'] & z.infer<typeof documentIdSchema>;
+export declare const documentReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    entity: z.ZodLiteral<"collection">;
+    slug: z.ZodString;
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+}, z.core.$strip>, z.ZodObject<{
+    entity: z.ZodLiteral<"global">;
+    slug: z.ZodString;
+}, z.core.$strip>], "entity">;
+export type DocumentReference = z.infer<typeof documentReferenceSchema>;
+export declare const isPopulated: <T extends TypeWithID>(relationship: T | DocumentID) => relationship is T;
+export declare function assertPopulated<T extends TypeWithID | null>(docsOrIds: (T | DocumentID)[], errorMessage?: (id: DocumentID) => string): T[];
+export declare function assertPopulated<T extends TypeWithID | null>(docOrId: T | DocumentID, errorMessage?: (id: DocumentID) => string): T;
+export type IdentifiableDocument = TypeWithID['id'] | TypeWithID;
+export declare function isIdentifiableDocument(value: unknown): value is IdentifiableDocument;
+export declare const resolveDocumentID: (entity: IdentifiableDocument) => DocumentID;
+export declare const uncaughtSwitchCase: (value: never) => never;
+export declare function fetchDocumentByReference(payload: BasePayload, ref: DocumentReference): Promise<JsonObject>;
+export declare function updateDocumentByReference(payload: BasePayload, ref: DocumentReference, data: JsonObject): Promise<JsonObject>;
+export { getAdminURL, getApiURL, getServerURL } from './urls';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAGX,UAAU,EACV,UAAU,EACX,MAAM,SAAS,CAAC;AACjB,OAAO,CAAC,MAAM,KAAK,CAAC;AAIpB,eAAO,MAAM,gBAAgB,iDAAoC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7E,eAAO,MAAM,uBAAuB;;;;;;;6BAUlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,UAAU,gBAChC,CAAC,GAAG,UAAU,KAC3B,YAAY,IAAI,CAAqC,CAAC;AAEzD,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,GAAG,IAAI,EACzD,SAAS,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,EAAE,EAC7B,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,MAAM,GACxC,CAAC,EAAE,CAAC;AACP,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,GAAG,IAAI,EACzD,OAAO,EAAE,CAAC,GAAG,UAAU,EACvB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,MAAM,GACxC,CAAC,CAAC;AAeL,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC;AAEjE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAO/B;AAED,eAAO,MAAM,iBAAiB,WAAY,oBAAoB,KAAG,UAChB,CAAC;AAElD,eAAO,MAAM,kBAAkB,UAAW,KAAK,UAE9C,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,UAAU,CAAC,CAgBrB;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,UAAU,uBAiBjB;AAED,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,76 @@
+import z from 'zod';
+// MARK: Types
+export const documentIdSchema = z.union([
+    z.number(),
+    z.string()
+]);
+export const documentReferenceSchema = z.discriminatedUnion('entity', [
+    z.object({
+        entity: z.literal('collection'),
+        slug: z.string(),
+        id: documentIdSchema
+    }),
+    z.object({
+        entity: z.literal('global'),
+        slug: z.string()
+    })
+]);
+// MARK: Type Guards
+export const isPopulated = (relationship)=>typeof relationship === 'object';
+export function assertPopulated(value, errorMessage = (id)=>`Doc is not populated: [${id}]`) {
+    if (value === null) return value;
+    if (Array.isArray(value)) {
+        return value.map((item)=>assertPopulated(item, errorMessage));
+    }
+    if (isPopulated(value)) return value;
+    throw new Error(errorMessage(value));
+}
+export function isIdentifiableDocument(value) {
+    if (typeof value === 'string') return true;
+    if (typeof value === 'number') return true;
+    if (value === null) return false;
+    if (typeof value !== 'object') return true;
+    if (!('id' in value)) return false;
+    return isIdentifiableDocument(value.id);
+}
+export const resolveDocumentID = (entity)=>typeof entity === 'object' ? entity.id : entity;
+export const uncaughtSwitchCase = (value)=>{
+    throw new Error(`Unhandled switch case: ${value}`);
+};
+export function fetchDocumentByReference(payload, ref) {
+    switch(ref.entity){
+        case 'collection':
+            return payload.findByID({
+                collection: ref.slug,
+                id: ref.id,
+                depth: 0
+            });
+        case 'global':
+            return payload.findGlobal({
+                slug: ref.slug,
+                depth: 0
+            });
+        default:
+            return uncaughtSwitchCase(ref);
+    }
+}
+export async function updateDocumentByReference(payload, ref, data) {
+    switch(ref.entity){
+        case 'collection':
+            return payload.update({
+                collection: ref.slug,
+                id: ref.id,
+                data: data
+            });
+        case 'global':
+            return payload.updateGlobal({
+                slug: ref.slug,
+                data: data
+            });
+        default:
+            return uncaughtSwitchCase(ref);
+    }
+}
+export { getAdminURL, getApiURL, getServerURL } from './urls';
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  BasePayload,\n  CollectionSlug,\n  GlobalSlug,\n  JsonObject,\n  TypeWithID,\n} from 'payload';\nimport z from 'zod';\n\n// MARK: Types\n\nexport const documentIdSchema = z.union([z.number(), z.string()]);\nexport type DocumentID = TypeWithID['id'] & z.infer<typeof documentIdSchema>;\n\nexport const documentReferenceSchema = z.discriminatedUnion('entity', [\n  z.object({\n    entity: z.literal('collection'),\n    slug: z.string(),\n    id: documentIdSchema,\n  }),\n  z.object({\n    entity: z.literal('global'),\n    slug: z.string(),\n  }),\n]);\n\nexport type DocumentReference = z.infer<typeof documentReferenceSchema>;\n\n// MARK: Type Guards\n\nexport const isPopulated = <T extends TypeWithID>(\n  relationship: T | DocumentID,\n): relationship is T => typeof relationship === 'object';\n\nexport function assertPopulated<T extends TypeWithID | null>(\n  docsOrIds: (T | DocumentID)[],\n  errorMessage?: (id: DocumentID) => string,\n): T[];\nexport function assertPopulated<T extends TypeWithID | null>(\n  docOrId: T | DocumentID,\n  errorMessage?: (id: DocumentID) => string,\n): T;\nexport function assertPopulated<T extends TypeWithID | null>(\n  value: T | DocumentID | (T | DocumentID)[],\n  errorMessage = (id: DocumentID) => `Doc is not populated: [${id}]`,\n): T | T[] {\n  if (value === null) return value;\n  if (Array.isArray(value)) {\n    return value.map((item) => assertPopulated(item, errorMessage));\n  }\n  if (isPopulated(value)) return value;\n  throw new Error(errorMessage(value as DocumentID));\n}\n\n// MARK: Utilities\n\nexport type IdentifiableDocument = TypeWithID['id'] | TypeWithID;\n\nexport function isIdentifiableDocument(\n  value: unknown,\n): value is IdentifiableDocument {\n  if (typeof value === 'string') return true;\n  if (typeof value === 'number') return true;\n  if (value === null) return false;\n  if (typeof value !== 'object') return true;\n  if (!('id' in value)) return false;\n  return isIdentifiableDocument(value.id);\n}\n\nexport const resolveDocumentID = (entity: IdentifiableDocument): DocumentID =>\n  typeof entity === 'object' ? entity.id : entity;\n\nexport const uncaughtSwitchCase = (value: never) => {\n  throw new Error(`Unhandled switch case: ${value}`);\n};\n\nexport function fetchDocumentByReference(\n  payload: BasePayload,\n  ref: DocumentReference,\n): Promise<JsonObject> {\n  switch (ref.entity) {\n    case 'collection':\n      return payload.findByID({\n        collection: ref.slug as CollectionSlug,\n        id: ref.id,\n        depth: 0,\n      });\n    case 'global':\n      return payload.findGlobal({\n        slug: ref.slug as GlobalSlug,\n        depth: 0,\n      });\n    default:\n      return uncaughtSwitchCase(ref);\n  }\n}\n\nexport async function updateDocumentByReference(\n  payload: BasePayload,\n  ref: DocumentReference,\n  data: JsonObject,\n) {\n  switch (ref.entity) {\n    case 'collection':\n      return payload.update({\n        collection: ref.slug as CollectionSlug,\n        id: ref.id,\n        data: data,\n      });\n    case 'global':\n      return payload.updateGlobal({\n        slug: ref.slug as GlobalSlug,\n        data: data as any,\n      });\n    default:\n      return uncaughtSwitchCase(ref);\n  }\n}\n\nexport { getAdminURL, getApiURL, getServerURL } from './urls';\n"],"names":["z","documentIdSchema","union","number","string","documentReferenceSchema","discriminatedUnion","object","entity","literal","slug","id","isPopulated","relationship","assertPopulated","value","errorMessage","Array","isArray","map","item","Error","isIdentifiableDocument","resolveDocumentID","uncaughtSwitchCase","fetchDocumentByReference","payload","ref","findByID","collection","depth","findGlobal","updateDocumentByReference","data","update","updateGlobal","getAdminURL","getApiURL","getServerURL"],"mappings":"AAOA,OAAOA,OAAO,MAAM;AAEpB,cAAc;AAEd,OAAO,MAAMC,mBAAmBD,EAAEE,KAAK,CAAC;IAACF,EAAEG,MAAM;IAAIH,EAAEI,MAAM;CAAG,EAAE;AAGlE,OAAO,MAAMC,0BAA0BL,EAAEM,kBAAkB,CAAC,UAAU;IACpEN,EAAEO,MAAM,CAAC;QACPC,QAAQR,EAAES,OAAO,CAAC;QAClBC,MAAMV,EAAEI,MAAM;QACdO,IAAIV;IACN;IACAD,EAAEO,MAAM,CAAC;QACPC,QAAQR,EAAES,OAAO,CAAC;QAClBC,MAAMV,EAAEI,MAAM;IAChB;CACD,EAAE;AAIH,oBAAoB;AAEpB,OAAO,MAAMQ,cAAc,CACzBC,eACsB,OAAOA,iBAAiB,SAAS;AAUzD,OAAO,SAASC,gBACdC,KAA0C,EAC1CC,eAAe,CAACL,KAAmB,CAAC,uBAAuB,EAAEA,GAAG,CAAC,CAAC;IAElE,IAAII,UAAU,MAAM,OAAOA;IAC3B,IAAIE,MAAMC,OAAO,CAACH,QAAQ;QACxB,OAAOA,MAAMI,GAAG,CAAC,CAACC,OAASN,gBAAgBM,MAAMJ;IACnD;IACA,IAAIJ,YAAYG,QAAQ,OAAOA;IAC/B,MAAM,IAAIM,MAAML,aAAaD;AAC/B;AAMA,OAAO,SAASO,uBACdP,KAAc;IAEd,IAAI,OAAOA,UAAU,UAAU,OAAO;IACtC,IAAI,OAAOA,UAAU,UAAU,OAAO;IACtC,IAAIA,UAAU,MAAM,OAAO;IAC3B,IAAI,OAAOA,UAAU,UAAU,OAAO;IACtC,IAAI,CAAE,CAAA,QAAQA,KAAI,GAAI,OAAO;IAC7B,OAAOO,uBAAuBP,MAAMJ,EAAE;AACxC;AAEA,OAAO,MAAMY,oBAAoB,CAACf,SAChC,OAAOA,WAAW,WAAWA,OAAOG,EAAE,GAAGH,OAAO;AAElD,OAAO,MAAMgB,qBAAqB,CAACT;IACjC,MAAM,IAAIM,MAAM,CAAC,uBAAuB,EAAEN,OAAO;AACnD,EAAE;AAEF,OAAO,SAASU,yBACdC,OAAoB,EACpBC,GAAsB;IAEtB,OAAQA,IAAInB,MAAM;QAChB,KAAK;YACH,OAAOkB,QAAQE,QAAQ,CAAC;gBACtBC,YAAYF,IAAIjB,IAAI;gBACpBC,IAAIgB,IAAIhB,EAAE;gBACVmB,OAAO;YACT;QACF,KAAK;YACH,OAAOJ,QAAQK,UAAU,CAAC;gBACxBrB,MAAMiB,IAAIjB,IAAI;gBACdoB,OAAO;YACT;QACF;YACE,OAAON,mBAAmBG;IAC9B;AACF;AAEA,OAAO,eAAeK,0BACpBN,OAAoB,EACpBC,GAAsB,EACtBM,IAAgB;IAEhB,OAAQN,IAAInB,MAAM;QAChB,KAAK;YACH,OAAOkB,QAAQQ,MAAM,CAAC;gBACpBL,YAAYF,IAAIjB,IAAI;gBACpBC,IAAIgB,IAAIhB,EAAE;gBACVsB,MAAMA;YACR;QACF,KAAK;YACH,OAAOP,QAAQS,YAAY,CAAC;gBAC1BzB,MAAMiB,IAAIjB,IAAI;gBACduB,MAAMA;YACR;QACF;YACE,OAAOT,mBAAmBG;IAC9B;AACF;AAEA,SAASS,WAAW,EAAEC,SAAS,EAAEC,YAAY,QAAQ,SAAS"}

package/dist/urls.d.ts

@@ -0,0 +1,11 @@
+import type { PayloadRequest } from 'payload';
+export declare function getServerURL(req: PayloadRequest): string;
+export declare function getAdminURL({ req, path, }: {
+    req: PayloadRequest;
+    path?: '' | `/${string}` | null;
+}): string;
+export declare function getApiURL({ req, path, }: {
+    req: PayloadRequest;
+    path?: '' | `/${string}` | null;
+}): string;
+//# sourceMappingURL=urls.d.ts.map

package/dist/urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../src/urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAWxD;AAED,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,IAAI,GACL,EAAE;IACD,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,MAAM,EAAE,GAAG,IAAI,CAAC;CACjC,GAAG,MAAM,CAMT;AAED,wBAAgB,SAAS,CAAC,EACxB,GAAG,EACH,IAAI,GACL,EAAE;IACD,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,MAAM,EAAE,GAAG,IAAI,CAAC;CACjC,GAAG,MAAM,CAMT"}

package/dist/urls.js

@@ -0,0 +1,23 @@
+import { formatAdminURL } from 'payload/shared';
+export function getServerURL(req) {
+    if (!req.url) throw new Error('Could not get serverURL, since request URL is not available');
+    const { config } = req.payload;
+    if (config.serverURL) return config.serverURL;
+    return `${new URL(req.url).protocol}//${req.headers.get('host')}`;
+}
+export function getAdminURL({ req, path }) {
+    return formatAdminURL({
+        adminRoute: req.payload.config.routes.admin,
+        serverURL: getServerURL(req),
+        path
+    });
+}
+export function getApiURL({ req, path }) {
+    return formatAdminURL({
+        apiRoute: req.payload.config.routes.api,
+        serverURL: getServerURL(req),
+        path
+    });
+}
+
+//# sourceMappingURL=urls.js.map

package/dist/urls.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/urls.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload';\nimport { formatAdminURL } from 'payload/shared';\n\nexport function getServerURL(req: PayloadRequest): string {\n  if (!req.url)\n    throw new Error(\n      'Could not get serverURL, since request URL is not available',\n    );\n\n  const { config } = req.payload;\n\n  if (config.serverURL) return config.serverURL;\n\n  return `${new URL(req.url).protocol}//${req.headers.get('host')}`;\n}\n\nexport function getAdminURL({\n  req,\n  path,\n}: {\n  req: PayloadRequest;\n  path?: '' | `/${string}` | null;\n}): string {\n  return formatAdminURL({\n    adminRoute: req.payload.config.routes.admin,\n    serverURL: getServerURL(req),\n    path,\n  });\n}\n\nexport function getApiURL({\n  req,\n  path,\n}: {\n  req: PayloadRequest;\n  path?: '' | `/${string}` | null;\n}): string {\n  return formatAdminURL({\n    apiRoute: req.payload.config.routes.api,\n    serverURL: getServerURL(req),\n    path,\n  });\n}\n"],"names":["formatAdminURL","getServerURL","req","url","Error","config","payload","serverURL","URL","protocol","headers","get","getAdminURL","path","adminRoute","routes","admin","getApiURL","apiRoute","api"],"mappings":"AACA,SAASA,cAAc,QAAQ,iBAAiB;AAEhD,OAAO,SAASC,aAAaC,GAAmB;IAC9C,IAAI,CAACA,IAAIC,GAAG,EACV,MAAM,IAAIC,MACR;IAGJ,MAAM,EAAEC,MAAM,EAAE,GAAGH,IAAII,OAAO;IAE9B,IAAID,OAAOE,SAAS,EAAE,OAAOF,OAAOE,SAAS;IAE7C,OAAO,GAAG,IAAIC,IAAIN,IAAIC,GAAG,EAAEM,QAAQ,CAAC,EAAE,EAAEP,IAAIQ,OAAO,CAACC,GAAG,CAAC,SAAS;AACnE;AAEA,OAAO,SAASC,YAAY,EAC1BV,GAAG,EACHW,IAAI,EAIL;IACC,OAAOb,eAAe;QACpBc,YAAYZ,IAAII,OAAO,CAACD,MAAM,CAACU,MAAM,CAACC,KAAK;QAC3CT,WAAWN,aAAaC;QACxBW;IACF;AACF;AAEA,OAAO,SAASI,UAAU,EACxBf,GAAG,EACHW,IAAI,EAIL;IACC,OAAOb,eAAe;QACpBkB,UAAUhB,IAAII,OAAO,CAACD,MAAM,CAACU,MAAM,CAACI,GAAG;QACvCZ,WAAWN,aAAaC;QACxBW;IACF;AACF"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@davincicoding/payload-utils",
+  "version": "0.0.1",
+  "description": "Shared utilities for Payload CMS plugins and applications.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davincicoding-org/payload-plugins.git",
+    "directory": "packages/utils"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./urls": {
+      "types": "./dist/urls.d.ts",
+      "import": "./dist/urls.js",
+      "default": "./dist/urls.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "swc src -d dist --config-file .swcrc --strip-leading-paths --ignore '**/*.test.ts' && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "check:types": "tsc --noEmit",
+    "clean": "rm -rf dist && rm -rf node_modules",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@swc/cli": "^0.6.0",
+    "@swc/core": "^1.11.0",
+    "@types/node": "^22.5.4",
+    "payload": "catalog:payload-stack",
+    "typescript": "catalog:payload-stack",
+    "vitest": "^3.1.2"
+  },
+  "peerDependencies": {
+    "payload": ">=3.72.0"
+  },
+  "engines": {
+    "node": "^18.20.2 || >=20.9.0"
+  }
+}