@quitecustard/payload 0.1.0

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.
Files changed (77) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +169 -0
  3. package/dist/access/anyone.d.ts +10 -0
  4. package/dist/access/anyone.js +9 -0
  5. package/dist/access/role-gate.d.ts +22 -0
  6. package/dist/access/role-gate.js +21 -0
  7. package/dist/access/self-access.d.ts +30 -0
  8. package/dist/access/self-access.js +34 -0
  9. package/dist/db/delete-many-with-versions.d.ts +21 -0
  10. package/dist/db/delete-many-with-versions.js +34 -0
  11. package/dist/db/external-ref.d.ts +65 -0
  12. package/dist/db/external-ref.js +88 -0
  13. package/dist/db/orphan-cleanup.d.ts +32 -0
  14. package/dist/db/orphan-cleanup.js +64 -0
  15. package/dist/db/sessions.d.ts +46 -0
  16. package/dist/db/sessions.js +50 -0
  17. package/dist/db/sql-result.d.ts +19 -0
  18. package/dist/db/sql-result.js +41 -0
  19. package/dist/db/sync-lock.d.ts +36 -0
  20. package/dist/db/sync-lock.js +116 -0
  21. package/dist/db/transaction-db.d.ts +13 -0
  22. package/dist/db/transaction-db.js +14 -0
  23. package/dist/documents/collection-versions.d.ts +10 -0
  24. package/dist/documents/collection-versions.js +17 -0
  25. package/dist/documents/locale-record.d.ts +12 -0
  26. package/dist/documents/locale-record.js +24 -0
  27. package/dist/documents/published-where.d.ts +21 -0
  28. package/dist/documents/published-where.js +17 -0
  29. package/dist/documents/resolve-ref.d.ts +29 -0
  30. package/dist/documents/resolve-ref.js +38 -0
  31. package/dist/errors/field-errors.d.ts +11 -0
  32. package/dist/errors/field-errors.js +16 -0
  33. package/dist/errors/is-duplicate-error.d.ts +14 -0
  34. package/dist/errors/is-duplicate-error.js +22 -0
  35. package/dist/errors/public-error.d.ts +17 -0
  36. package/dist/errors/public-error.js +26 -0
  37. package/dist/fields/colour-options-field.d.ts +18 -0
  38. package/dist/fields/colour-options-field.js +44 -0
  39. package/dist/fields/colour-picker-field.d.ts +12 -0
  40. package/dist/fields/colour-picker-field.js +11 -0
  41. package/dist/fields/height-field.d.ts +12 -0
  42. package/dist/fields/height-field.js +11 -0
  43. package/dist/fields/hero-field.d.ts +16 -0
  44. package/dist/fields/hero-field.js +50 -0
  45. package/dist/fields/layout-fields.d.ts +7 -0
  46. package/dist/fields/layout-fields.js +47 -0
  47. package/dist/fields/link-field.d.ts +34 -0
  48. package/dist/fields/link-field.js +170 -0
  49. package/dist/fields/media-content-fields.d.ts +23 -0
  50. package/dist/fields/media-content-fields.js +103 -0
  51. package/dist/fields/owner-field.d.ts +19 -0
  52. package/dist/fields/owner-field.js +53 -0
  53. package/dist/fields/phone-field.d.ts +12 -0
  54. package/dist/fields/phone-field.js +11 -0
  55. package/dist/fields/seo-tab.d.ts +18 -0
  56. package/dist/fields/seo-tab.js +36 -0
  57. package/dist/fields/size-field.d.ts +8 -0
  58. package/dist/fields/size-field.js +19 -0
  59. package/dist/fields/social-url.d.ts +21 -0
  60. package/dist/fields/social-url.js +49 -0
  61. package/dist/fields/spacing-select-field.d.ts +17 -0
  62. package/dist/fields/spacing-select-field.js +36 -0
  63. package/dist/internal/component-field.d.ts +25 -0
  64. package/dist/internal/component-field.js +24 -0
  65. package/dist/operations/after-response.d.ts +24 -0
  66. package/dist/operations/after-response.js +40 -0
  67. package/dist/operations/publish-transition.d.ts +45 -0
  68. package/dist/operations/publish-transition.js +78 -0
  69. package/dist/operations/run-queued-jobs.d.ts +30 -0
  70. package/dist/operations/run-queued-jobs.js +87 -0
  71. package/dist/operations/suppress-context.d.ts +16 -0
  72. package/dist/operations/suppress-context.js +55 -0
  73. package/dist/operations/unique-slug.d.ts +12 -0
  74. package/dist/operations/unique-slug.js +23 -0
  75. package/dist/operations/unique-username.d.ts +40 -0
  76. package/dist/operations/unique-username.js +52 -0
  77. package/package.json +76 -0
@@ -0,0 +1,12 @@
1
+ /**
2
+ * A slug derived from `base` that is not already taken, appending an incrementing numeric suffix
3
+ * (from 2) until `isTaken` returns false.
4
+ *
5
+ * `normalise` defaults to `normaliseSlug`; pass `normaliseUsernameSlug` for handles, so the
6
+ * suffixed candidates don't re-strip the dots and underscores it preserves.
7
+ *
8
+ * Throws when `base` has no slug-safe characters at all - an emoji-only or purely punctuation name
9
+ * normalises to `''`, and an empty slug would otherwise be returned as if it were a valid one.
10
+ * The caller owns that fallback, since only it knows what to name the doc.
11
+ */
12
+ export declare const uniqueSuffixedSlug: (base: string, isTaken: (slug: string) => boolean | Promise<boolean>, normalise?: (input?: string) => string) => Promise<string>;
@@ -0,0 +1,23 @@
1
+ import { normaliseSlug } from '@quitecustard/core/format/normalise';
2
+ /**
3
+ * A slug derived from `base` that is not already taken, appending an incrementing numeric suffix
4
+ * (from 2) until `isTaken` returns false.
5
+ *
6
+ * `normalise` defaults to `normaliseSlug`; pass `normaliseUsernameSlug` for handles, so the
7
+ * suffixed candidates don't re-strip the dots and underscores it preserves.
8
+ *
9
+ * Throws when `base` has no slug-safe characters at all - an emoji-only or purely punctuation name
10
+ * normalises to `''`, and an empty slug would otherwise be returned as if it were a valid one.
11
+ * The caller owns that fallback, since only it knows what to name the doc.
12
+ */
13
+ export const uniqueSuffixedSlug = async (base, isTaken, normalise = normaliseSlug) => {
14
+ const baseSlug = normalise(base);
15
+ if (!baseSlug)
16
+ throw new Error(`Cannot derive a slug from ${JSON.stringify(base)}`);
17
+ if (!(await isTaken(baseSlug)))
18
+ return baseSlug;
19
+ let suffix = 2;
20
+ while (await isTaken(normalise(`${base}-${suffix}`)))
21
+ suffix++;
22
+ return normalise(`${base}-${suffix}`);
23
+ };
@@ -0,0 +1,40 @@
1
+ import type { BasePayload, CollectionSlug } from 'payload';
2
+ /** Which collection and column hold the usernames being allocated from. */
3
+ export type UniqueUsernameOptions = {
4
+ /** Auth collection the usernames live in. Defaults to `users`. */
5
+ collection?: CollectionSlug;
6
+ /** Field holding the username. Defaults to `username`. */
7
+ field?: string;
8
+ /**
9
+ * Names already handed out in memory, treated as taken. For a bulk caller creating many users
10
+ * concurrently in one run; each candidate this resolves is added to the set.
11
+ */
12
+ reserved?: Set<string>;
13
+ };
14
+ /**
15
+ * A username derived from `base` that nobody currently holds - the base itself where it is free,
16
+ * otherwise a numeric suffix.
17
+ *
18
+ * ```ts
19
+ * const username = await resolveUniqueUsername('ada.lovelace', payload)
20
+ * const handle = await resolveUniqueUsername(name, payload, { collection: 'members', field: 'handle' })
21
+ * ```
22
+ *
23
+ * Each candidate is checked with its own exact-match count rather than prefetching lookalikes with
24
+ * `like`: a prefetch capped at N rows goes blind past N matches and can hand back a name that IS
25
+ * taken, failing the create on the unique constraint. The common case costs one query.
26
+ *
27
+ * `reserved` candidates are claimed SYNCHRONOUSLY, before the DB probe's await yields, so two
28
+ * parallel allocations can never probe the same candidate and both see it free. A candidate the DB
29
+ * then reports taken stays reserved; burning it costs nothing, since handing it to a sibling would
30
+ * only fail their create.
31
+ *
32
+ * Two simultaneous creates in DIFFERENT processes can still reach the same answer. Keep the unique
33
+ * index on the column as the backstop: the loser's create throws, and the caller retries with a
34
+ * fresh resolve.
35
+ *
36
+ * Throws when `base` has no slug-safe characters at all, matching `uniqueSuffixedSlug` - otherwise
37
+ * an emoji-only or purely punctuation name would normalise to '', and every such base would collide
38
+ * on the same empty username.
39
+ */
40
+ export declare const resolveUniqueUsername: (base: string, payload: BasePayload, { collection, field, reserved }?: UniqueUsernameOptions) => Promise<string>;
@@ -0,0 +1,52 @@
1
+ import { normaliseUsernameSlug } from '@quitecustard/core/format/normalise';
2
+ /**
3
+ * A username derived from `base` that nobody currently holds - the base itself where it is free,
4
+ * otherwise a numeric suffix.
5
+ *
6
+ * ```ts
7
+ * const username = await resolveUniqueUsername('ada.lovelace', payload)
8
+ * const handle = await resolveUniqueUsername(name, payload, { collection: 'members', field: 'handle' })
9
+ * ```
10
+ *
11
+ * Each candidate is checked with its own exact-match count rather than prefetching lookalikes with
12
+ * `like`: a prefetch capped at N rows goes blind past N matches and can hand back a name that IS
13
+ * taken, failing the create on the unique constraint. The common case costs one query.
14
+ *
15
+ * `reserved` candidates are claimed SYNCHRONOUSLY, before the DB probe's await yields, so two
16
+ * parallel allocations can never probe the same candidate and both see it free. A candidate the DB
17
+ * then reports taken stays reserved; burning it costs nothing, since handing it to a sibling would
18
+ * only fail their create.
19
+ *
20
+ * Two simultaneous creates in DIFFERENT processes can still reach the same answer. Keep the unique
21
+ * index on the column as the backstop: the loser's create throws, and the caller retries with a
22
+ * fresh resolve.
23
+ *
24
+ * Throws when `base` has no slug-safe characters at all, matching `uniqueSuffixedSlug` - otherwise
25
+ * an emoji-only or purely punctuation name would normalise to '', and every such base would collide
26
+ * on the same empty username.
27
+ */
28
+ export const resolveUniqueUsername = async (base, payload, { collection = 'users', field = 'username', reserved } = {}) => {
29
+ const normalised = normaliseUsernameSlug(base);
30
+ if (!normalised)
31
+ throw new Error(`Cannot derive a username from ${JSON.stringify(base)}`);
32
+ // Claims the i-th candidate unless a parallel allocation already holds it. Synchronous on purpose
33
+ // - no await between the reserved check and the add (see above).
34
+ const claimCandidate = (i) => {
35
+ const candidate = i === 0 ? normalised : `${normalised}${i}`;
36
+ if (reserved?.has(candidate))
37
+ return undefined;
38
+ reserved?.add(candidate);
39
+ return candidate;
40
+ };
41
+ for (let i = 0;; i++) {
42
+ const candidate = claimCandidate(i);
43
+ if (!candidate)
44
+ continue;
45
+ const { totalDocs } = await payload.count({
46
+ collection,
47
+ where: { [field]: { equals: candidate } },
48
+ });
49
+ if (totalDocs === 0)
50
+ return candidate;
51
+ }
52
+ };
package/package.json ADDED
@@ -0,0 +1,76 @@
1
+ {
2
+ "name": "@quitecustard/payload",
3
+ "version": "0.1.0",
4
+ "description": "Payload v3 helpers: relation narrowing, transactions, autosave-vs-unpublish detection, sync locks, unique slugs and usernames",
5
+ "keywords": [
6
+ "payload",
7
+ "payloadcms",
8
+ "cms",
9
+ "helpers",
10
+ "typescript"
11
+ ],
12
+ "license": "MIT",
13
+ "author": "QuiteCustard",
14
+ "homepage": "https://github.com/QuiteCustard/custard-kit/tree/HEAD/packages/payload#readme",
15
+ "bugs": "https://github.com/QuiteCustard/custard-kit/issues",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/QuiteCustard/custard-kit.git",
19
+ "directory": "packages/payload"
20
+ },
21
+ "type": "module",
22
+ "engines": {
23
+ "node": ">=20"
24
+ },
25
+ "sideEffects": false,
26
+ "files": [
27
+ "dist"
28
+ ],
29
+ "publishConfig": {
30
+ "access": "public"
31
+ },
32
+ "exports": {
33
+ "./internal/*": null,
34
+ "./*": {
35
+ "types": "./dist/*.d.ts",
36
+ "import": "./dist/*.js"
37
+ }
38
+ },
39
+ "dependencies": {
40
+ "@quitecustard/core": "^0.1.0"
41
+ },
42
+ "peerDependencies": {
43
+ "@payloadcms/drizzle": "^3.0.0",
44
+ "@payloadcms/plugin-seo": "^3.0.0",
45
+ "drizzle-orm": "^0.45.0",
46
+ "next": "^16.0.0",
47
+ "payload": "^3.0.0"
48
+ },
49
+ "peerDependenciesMeta": {
50
+ "@payloadcms/drizzle": {
51
+ "optional": true
52
+ },
53
+ "drizzle-orm": {
54
+ "optional": true
55
+ },
56
+ "@payloadcms/plugin-seo": {
57
+ "optional": true
58
+ },
59
+ "next": {
60
+ "optional": true
61
+ }
62
+ },
63
+ "devDependencies": {
64
+ "@payloadcms/db-vercel-postgres": "3.88.0",
65
+ "@payloadcms/drizzle": "3.88.0",
66
+ "@payloadcms/plugin-seo": "3.88.0",
67
+ "@types/node": "22.19.9",
68
+ "drizzle-orm": "0.45.2",
69
+ "next": "16.3.1",
70
+ "payload": "3.88.0"
71
+ },
72
+ "scripts": {
73
+ "build": "tsc -p tsconfig.build.json",
74
+ "typecheck": "tsc -p tsconfig.json"
75
+ }
76
+ }