From 146549d10fc7169e83e5e8cc96ce5027702725bf Mon Sep 17 00:00:00 2001 From: techiejd <62455039+techiejd@users.noreply.github.com> Date: Sun, 31 May 2026 23:44:33 +0700 Subject: [PATCH 1/5] build(cf): add @cloudflare/workers-types devDependency --- adapters/cf/package.json | 1 + pnpm-lock.yaml | 40 +++++++++++++++++++++++++--------------- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/adapters/cf/package.json b/adapters/cf/package.json index 60f0f1b..67c9c57 100644 --- a/adapters/cf/package.json +++ b/adapters/cf/package.json @@ -30,6 +30,7 @@ "payloadcms-vectorize": ">=1.0.0" }, "devDependencies": { + "@cloudflare/workers-types": "^4.20240000.0", "payloadcms-vectorize": "workspace:*" }, "engines": { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c9e19e1..28b5ddf 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -19,10 +19,10 @@ importers: version: 3.3.3 '@payloadcms/db-postgres': specifier: 3.69.0 - version: 3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3)) + version: 3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3)) '@payloadcms/db-sqlite': specifier: 3.69.0 - version: 3.69.0(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3) + version: 3.69.0(@cloudflare/workers-types@4.20260531.1)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3) '@payloadcms/eslint-config': specifier: 3.9.0 version: 3.9.0(@typescript-eslint/eslint-plugin@8.51.0(@typescript-eslint/parser@8.51.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.7.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.7.3))(jest@30.2.0(@types/node@22.19.3)(babel-plugin-macros@3.1.0)(esbuild-register@3.6.0(esbuild@0.25.12)))(jiti@2.6.1) @@ -153,6 +153,9 @@ importers: specifier: '>=3.0.0 <4.0.0' version: 3.69.0(graphql@16.12.0)(typescript@5.7.3) devDependencies: + '@cloudflare/workers-types': + specifier: ^4.20240000.0 + version: 4.20260531.1 payloadcms-vectorize: specifier: workspace:* version: link:../.. @@ -180,7 +183,7 @@ importers: dependencies: '@payloadcms/db-postgres': specifier: '>=3.0.0 <4.0.0' - version: 3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3)) + version: 3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3)) payload: specifier: '>=3.0.0 <4.0.0' version: 3.69.0(graphql@16.12.0)(typescript@5.7.3) @@ -457,6 +460,9 @@ packages: '@changesets/write@0.4.0': resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==} + '@cloudflare/workers-types@4.20260531.1': + resolution: {integrity: sha512-7DybhbX12n+mVgJEDvm9W/jjqpaUIczg+RWj1Hua9nGEG+pNJnT+yZj1JKENrbdyuGWx3OFEgUCNFcGJN86Dvg==} + '@date-fns/tz@1.2.0': resolution: {integrity: sha512-LBrd7MiJZ9McsOgxqWX7AaxrDjcFVjWH/tIKJd7pnR7McaslGYOP1QmmiBXdJH/H/yLCT+rcQ7FaPBUxRGUtrg==} @@ -7225,6 +7231,8 @@ snapshots: human-id: 4.1.3 prettier: 2.8.8 + '@cloudflare/workers-types@4.20260531.1': {} + '@date-fns/tz@1.2.0': {} '@dnd-kit/accessibility@3.1.1(react@19.1.0)': @@ -8649,13 +8657,13 @@ snapshots: - socks - supports-color - '@payloadcms/db-postgres@3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))': + '@payloadcms/db-postgres@3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))': dependencies: - '@payloadcms/drizzle': 3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3) + '@payloadcms/drizzle': 3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3) '@types/pg': 8.10.2 console-table-printer: 2.12.1 drizzle-kit: 0.31.7 - drizzle-orm: 0.44.7(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(pg@8.16.3) + drizzle-orm: 0.44.7(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(pg@8.16.3) payload: 3.69.0(graphql@16.12.0)(typescript@5.7.3) pg: 8.16.3 prompts: 2.4.2 @@ -8692,13 +8700,13 @@ snapshots: - sqlite3 - supports-color - '@payloadcms/db-sqlite@3.69.0(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3)': + '@payloadcms/db-sqlite@3.69.0(@cloudflare/workers-types@4.20260531.1)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3)': dependencies: '@libsql/client': 0.14.0 - '@payloadcms/drizzle': 3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3) + '@payloadcms/drizzle': 3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3) console-table-printer: 2.12.1 drizzle-kit: 0.31.7 - drizzle-orm: 0.44.7(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(pg@8.16.3) + drizzle-orm: 0.44.7(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(pg@8.16.3) payload: 3.69.0(graphql@16.12.0)(typescript@5.7.3) prompts: 2.4.2 to-snake-case: 1.0.0 @@ -8736,11 +8744,11 @@ snapshots: - supports-color - utf-8-validate - '@payloadcms/drizzle@3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3)': + '@payloadcms/drizzle@3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3)': dependencies: console-table-printer: 2.12.1 dequal: 2.0.3 - drizzle-orm: 0.44.7(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(pg@8.16.3) + drizzle-orm: 0.44.7(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(pg@8.16.3) payload: 3.69.0(graphql@16.12.0)(typescript@5.7.3) prompts: 2.4.2 to-snake-case: 1.0.0 @@ -8776,11 +8784,11 @@ snapshots: - sql.js - sqlite3 - '@payloadcms/drizzle@3.69.0(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3)': + '@payloadcms/drizzle@3.69.0(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(payload@3.69.0(graphql@16.12.0)(typescript@5.7.3))(pg@8.16.3)': dependencies: console-table-printer: 2.12.1 dequal: 2.0.3 - drizzle-orm: 0.44.7(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(pg@8.16.3) + drizzle-orm: 0.44.7(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(pg@8.16.3) payload: 3.69.0(graphql@16.12.0)(typescript@5.7.3) prompts: 2.4.2 to-snake-case: 1.0.0 @@ -10671,15 +10679,17 @@ snapshots: transitivePeerDependencies: - supports-color - drizzle-orm@0.44.7(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(pg@8.16.3): + drizzle-orm@0.44.7(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.10.2)(pg@8.16.3): optionalDependencies: + '@cloudflare/workers-types': 4.20260531.1 '@libsql/client': 0.14.0 '@opentelemetry/api': 1.9.0 '@types/pg': 8.10.2 pg: 8.16.3 - drizzle-orm@0.44.7(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(pg@8.16.3): + drizzle-orm@0.44.7(@cloudflare/workers-types@4.20260531.1)(@libsql/client@0.14.0)(@opentelemetry/api@1.9.0)(@types/pg@8.16.0)(pg@8.16.3): optionalDependencies: + '@cloudflare/workers-types': 4.20260531.1 '@libsql/client': 0.14.0 '@opentelemetry/api': 1.9.0 '@types/pg': 8.16.0 From 0af470cf45219416ad9c417117a44f8bb858ef39 Mon Sep 17 00:00:00 2001 From: techiejd <62455039+techiejd@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:59:09 +0700 Subject: [PATCH 2/5] refactor(cf): adopt @cloudflare/workers-types Vectorize binding --- adapters/cf/src/types.ts | 54 ++++------------------------------------ 1 file changed, 5 insertions(+), 49 deletions(-) diff --git a/adapters/cf/src/types.ts b/adapters/cf/src/types.ts index 92786d4..e10e441 100644 --- a/adapters/cf/src/types.ts +++ b/adapters/cf/src/types.ts @@ -1,65 +1,21 @@ +/// import type { BasePayload } from 'payload' import { getVectorizedPayload } from 'payloadcms-vectorize' -/** - * Retrieve the Cloudflare Vectorize binding from a Payload instance. - * Throws if the binding is not found. - */ -export function getVectorizeBinding(payload: BasePayload): CloudflareVectorizeBinding { +export function getVectorizeBinding(payload: BasePayload): Vectorize { const binding = getVectorizedPayload(payload)?.getDbAdapterCustom() - ?._vectorizeBinding as CloudflareVectorizeBinding | undefined + ?._vectorizeBinding as Vectorize | undefined if (!binding) { throw new Error('[@payloadcms-vectorize/cf] Cloudflare Vectorize binding not found') } return binding } -/** - * Configuration for a knowledge pool in Cloudflare Vectorize - */ export interface CloudflareVectorizePoolConfig { - /** Vector dimensions for this pool (must match embedding model output) */ dims: number } -/** - * All knowledge pools configuration for Cloudflare Vectorize - */ export type KnowledgePoolsConfig = Record -/** A single vector match returned by a Vectorize query */ -export interface VectorizeMatch { - id: string - score?: number - metadata?: Record -} - -/** Result of a Vectorize query */ -export interface VectorizeQueryResult { - matches: VectorizeMatch[] - count: number -} - -/** Vector to upsert into Vectorize */ -export interface VectorizeVector { - id: string - values: number[] - metadata?: Record -} - -/** - * Cloudflare Vectorize binding interface. - * Mirrors the subset of the Vectorize API we use. - * For the full type, install `@cloudflare/workers-types`. - */ -export interface CloudflareVectorizeBinding { - query(vector: number[], options?: { - topK?: number - returnMetadata?: boolean | 'indexed' | 'all' - filter?: Record - /** Vectorize metadata filtering */ - where?: Record - }): Promise - upsert(vectors: VectorizeVector[]): Promise - deleteByIds(ids: string[]): Promise -} +/** @deprecated Use the official `Vectorize` type from `@cloudflare/workers-types`. */ +export type CloudflareVectorizeBinding = Vectorize From fb98908ad183fdd5dbbc15169a17f305a85c971d Mon Sep 17 00:00:00 2001 From: techiejd <62455039+techiejd@users.noreply.github.com> Date: Mon, 1 Jun 2026 17:22:04 +0700 Subject: [PATCH 3/5] docs(cf): restore JSDoc on retained types after binding swap --- adapters/cf/src/types.ts | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/adapters/cf/src/types.ts b/adapters/cf/src/types.ts index e10e441..a0fd6c7 100644 --- a/adapters/cf/src/types.ts +++ b/adapters/cf/src/types.ts @@ -2,6 +2,10 @@ import type { BasePayload } from 'payload' import { getVectorizedPayload } from 'payloadcms-vectorize' +/** + * Retrieve the Cloudflare Vectorize binding from a Payload instance. + * Throws if the binding is not found. + */ export function getVectorizeBinding(payload: BasePayload): Vectorize { const binding = getVectorizedPayload(payload)?.getDbAdapterCustom() ?._vectorizeBinding as Vectorize | undefined @@ -11,10 +15,17 @@ export function getVectorizeBinding(payload: BasePayload): Vectorize { return binding } +/** + * Configuration for a knowledge pool in Cloudflare Vectorize + */ export interface CloudflareVectorizePoolConfig { + /** Vector dimensions for this pool (must match embedding model output) */ dims: number } +/** + * All knowledge pools configuration for Cloudflare Vectorize + */ export type KnowledgePoolsConfig = Record /** @deprecated Use the official `Vectorize` type from `@cloudflare/workers-types`. */ From 39c17dc372a291711519aaca9d30c943acf958a3 Mon Sep 17 00:00:00 2001 From: techiejd <62455039+techiejd@users.noreply.github.com> Date: Mon, 1 Jun 2026 17:49:31 +0700 Subject: [PATCH 4/5] build: stop root tsconfig from typechecking adapter sources The CF adapter's '/// ' pulls in Workers ambient globals that redefine Request/Response (where .json() returns unknown, not the DOM's any). The root tsconfig included ./adapters/*/src/**, so 'tsc --noEmit' (build:types:all) leaked those globals into core endpoint/admin code and failed typecheck. Adapters are already typechecked independently via their own tsconfig.build.json in the CI build job, so root coverage of adapter sources was redundant. --- tsconfig.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsconfig.json b/tsconfig.json index 8c2fdbc..2622313 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -22,5 +22,5 @@ } ] }, - "include": ["./src/**/*.ts", "./src/**/*.tsx", "./adapters/*/src/**/*.ts", "./dev/next-env.d.ts"] + "include": ["./src/**/*.ts", "./src/**/*.tsx", "./dev/next-env.d.ts"] } From 963a5d1c47ac66de9df7becde477649dfd5f242e Mon Sep 17 00:00:00 2001 From: techiejd <62455039+techiejd@users.noreply.github.com> Date: Wed, 3 Jun 2026 19:59:25 +0700 Subject: [PATCH 5/5] refactor(cf): narrow Vectorize binding to the methods the adapter uses Depend on Pick via a named VectorizeBinding type instead of the full 8-method Vectorize contract. env.VECTORIZE remains assignable; CloudflareVectorizeBinding is kept as a deprecated alias for back-compat. --- adapters/cf/src/index.ts | 6 +++--- adapters/cf/src/types.ts | 13 +++++++++---- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/adapters/cf/src/index.ts b/adapters/cf/src/index.ts index dd78a3e..f3a51bb 100644 --- a/adapters/cf/src/index.ts +++ b/adapters/cf/src/index.ts @@ -1,7 +1,7 @@ import type { CollectionSlug } from 'payload' import type { DbAdapter } from 'payloadcms-vectorize' import { getVectorizeBinding } from './types.js' -import type { CloudflareVectorizeBinding, KnowledgePoolsConfig } from './types.js' +import type { CloudflareVectorizeBinding, KnowledgePoolsConfig, VectorizeBinding } from './types.js' import cfMappingsCollection, { CF_MAPPINGS_SLUG } from './collections/cfMappings.js' import embed from './embed.js' import search from './search.js' @@ -13,7 +13,7 @@ interface CloudflareVectorizeConfig { /** Knowledge pools configuration with their dimensions */ config: KnowledgePoolsConfig /** Cloudflare Vectorize binding for vector storage */ - binding: CloudflareVectorizeBinding + binding: VectorizeBinding } /** @@ -134,5 +134,5 @@ export const createCloudflareVectorizeIntegration = ( } export { CF_MAPPINGS_SLUG } from './collections/cfMappings.js' -export type { CloudflareVectorizeBinding, KnowledgePoolsConfig } +export type { CloudflareVectorizeBinding, KnowledgePoolsConfig, VectorizeBinding } export type { KnowledgePoolsConfig as KnowledgePoolConfig } diff --git a/adapters/cf/src/types.ts b/adapters/cf/src/types.ts index a0fd6c7..1cecab2 100644 --- a/adapters/cf/src/types.ts +++ b/adapters/cf/src/types.ts @@ -2,13 +2,18 @@ import type { BasePayload } from 'payload' import { getVectorizedPayload } from 'payloadcms-vectorize' +/** + * The subset of the Cloudflare `Vectorize` binding used by this adapter. + */ +export type VectorizeBinding = Pick + /** * Retrieve the Cloudflare Vectorize binding from a Payload instance. * Throws if the binding is not found. */ -export function getVectorizeBinding(payload: BasePayload): Vectorize { +export function getVectorizeBinding(payload: BasePayload): VectorizeBinding { const binding = getVectorizedPayload(payload)?.getDbAdapterCustom() - ?._vectorizeBinding as Vectorize | undefined + ?._vectorizeBinding as VectorizeBinding | undefined if (!binding) { throw new Error('[@payloadcms-vectorize/cf] Cloudflare Vectorize binding not found') } @@ -28,5 +33,5 @@ export interface CloudflareVectorizePoolConfig { */ export type KnowledgePoolsConfig = Record -/** @deprecated Use the official `Vectorize` type from `@cloudflare/workers-types`. */ -export type CloudflareVectorizeBinding = Vectorize +/** @deprecated Use {@link VectorizeBinding}. */ +export type CloudflareVectorizeBinding = VectorizeBinding