@lunora/platform 1.0.0-alpha.27 → 1.0.0-alpha.28

package/dist/index.d.mts

@@ -292,30 +292,53 @@ type KvNamespaceListResult<Metadata = unknown> = {
   list_complete: true;
 };
 /**
- * Minimal structural projection of `VectorizeIndex` so unit tests can pass a
+ * Minimal structural projection of `Vectorize` so unit tests can pass a
  * plain-object double and the real Cloudflare binding satisfies the same shape.
  * Mirrors the surface documented at
  * https://developers.cloudflare.com/vectorize/reference/client-api/.
+ *
+ * **Method** syntax, not arrow properties: `ReadonlyArray` is the correct (wider)
+ * parameter type, but an arrow property makes parameters strictly contravariant
+ * under `strictFunctionTypes`, and Cloudflare declares `deleteByIds(ids: string[])`
+ * — so the real binding did not satisfy this interface at all. Methods are checked
+ * bivariantly, which admits both it and a `readonly`-clean double.
+ * `binding-assignability.test-d.ts` in `@lunora/bindings` pins that against the
+ * published types. `this: void` keeps the members usable as bare references, which
+ * is what every `expect(double.query)` assertion in those tests does.
  */
 interface VectorizeIndexLike {
-  deleteByIds: (ids: ReadonlyArray<string>) => Promise<VectorizeDeleteMutation>;
-  describe?: () => Promise<VectorizeIndexDetails>;
-  getByIds: (ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorizeVector>>;
-  insert: (vectors: ReadonlyArray<VectorizeVector>) => Promise<VectorizeUpsertMutation>;
-  query: (vector: ReadonlyArray<number>, options?: VectorizeQueryOptions) => Promise<VectorizeMatches>;
-  upsert: (vectors: ReadonlyArray<VectorizeVector>) => Promise<VectorizeUpsertMutation>;
+  deleteByIds(this: void, ids: ReadonlyArray<string>): Promise<VectorizeDeleteMutation>;
+  describe?(this: void): Promise<VectorizeIndexDetails>;
+  getByIds(this: void, ids: ReadonlyArray<string>): Promise<ReadonlyArray<VectorizeVector>>;
+  insert(this: void, vectors: ReadonlyArray<VectorizeVector>): Promise<VectorizeUpsertMutation>;
+  query(this: void, vector: VectorValues, options?: VectorizeQueryOptions): Promise<VectorizeMatches>;
+  upsert(this: void, vectors: ReadonlyArray<VectorizeVector>): Promise<VectorizeUpsertMutation>;
 }
 type VectorMetric = "cosine" | "euclidean" | "dot-product";
+/**
+ * An embedding, as either a plain array or one of the typed arrays Vectorize
+ * accepts. The typed-array arms are not a convenience: Cloudflare's own
+ * `VectorizeVector.values` is `VectorFloatArray | number[]`, so a projection
+ * limited to `ReadonlyArray<number>` excluded every vector the real binding
+ * returns. Read one with `Array.from(...)` rather than an array method.
+ */
+type VectorValues = Float32Array | Float64Array | ReadonlyArray<number>;
 interface VectorizeVector {
   id: string;
   metadata?: Record<string, unknown>;
   namespace?: string;
-  values: ReadonlyArray<number>;
+  values: VectorValues;
 }
+/**
+ * Query options, kept a superset of Cloudflare's own `VectorizeQueryOptions` so
+ * the real binding satisfies {@link VectorizeIndexLike}. `returnMetadata` carries
+ * the legacy `boolean` arm for that reason - pass one of the three levels; the
+ * boolean is what Cloudflare still accepts, not what callers should write.
+ */
 interface VectorizeQueryOptions {
   filter?: Record<string, unknown>;
   namespace?: string;
-  returnMetadata?: "none" | "indexed" | "all";
+  returnMetadata?: "none" | "indexed" | "all" | boolean;
   returnValues?: boolean;
   topK?: number;
 }
@@ -324,7 +347,7 @@ interface VectorizeMatch {
   metadata?: Record<string, unknown>;
   namespace?: string;
   score: number;
-  values?: ReadonlyArray<number>;
+  values?: VectorValues;
 }
 interface VectorizeMatches {
   count: number;
@@ -337,11 +360,24 @@ interface VectorizeDeleteMutation {
   count?: number;
   mutationId: string;
 }
+/**
+ * What `describe()` reports. Both spellings of the row count are optional because
+ * Cloudflare renamed it between API generations — the beta `VectorizeIndex`
+ * returns `vectorsCount`, the current `Vectorize` returns `vectorCount` — and a
+ * projection that required either one excluded a real binding. Read them as
+ * `vectorCount ?? vectorsCount`.
+ *
+ * `processedUpTo*` are typed loosely for the same reason: documented as ISO 8601
+ * strings, typed as `number` in `@cloudflare/workers-types`.
+ */
 interface VectorizeIndexDetails {
   dimensions: number;
-  processedUpToDatetime?: string;
-  processedUpToMutation?: string;
-  vectorsCount: number;
+  processedUpToDatetime?: number | string;
+  processedUpToMutation?: number | string;
+  /** The current `Vectorize.describe()` spelling. */
+  vectorCount?: number;
+  /** The beta `VectorizeIndex.describe()` spelling. */
+  vectorsCount?: number;
 }
 /**
  * A single-range read against R2: an `{ offset, length }` window (at least one
@@ -906,4 +942,4 @@ export { type AnalyticsEngineDataPoint, type AnalyticsEngineDataPointLike, type
  * workerd, Node). It is intended to be the leaf dependency every other
  * `@lunora/*` package can import without creating cycles.
  */
-type ExecutionContextLike, type HttpCacheLike, type HttpCacheQueryOptions, type KVNamespaceLike, type KvGetOptions, type KvListKey, type KvNamespaceListResult, type KvNamespacePutOptions, type KvValue, type KvValueType, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, NODE_CAPABILITIES, NOOP_EXECUTION_CONTEXT, type PlatformCapabilities, type QueueBindingLike, type QueueContentType, type QueueMessageLike, type QueueRetryOptions, type QueueSendBatchOptions, type QueueSendOptions, type QueueSendOptionsLike, type QueueSendRequestLike, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2UploadedPartLike, type VectorMatchLike, type VectorMetric, type VectorRecordLike, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector };
+type ExecutionContextLike, type HttpCacheLike, type HttpCacheQueryOptions, type KVNamespaceLike, type KvGetOptions, type KvListKey, type KvNamespaceListResult, type KvNamespacePutOptions, type KvValue, type KvValueType, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, NODE_CAPABILITIES, NOOP_EXECUTION_CONTEXT, type PlatformCapabilities, type QueueBindingLike, type QueueContentType, type QueueMessageLike, type QueueRetryOptions, type QueueSendBatchOptions, type QueueSendOptions, type QueueSendOptionsLike, type QueueSendRequestLike, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2UploadedPartLike, type VectorMatchLike, type VectorMetric, type VectorRecordLike, type VectorValues, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector };

package/dist/index.d.ts

@@ -292,30 +292,53 @@ type KvNamespaceListResult<Metadata = unknown> = {
   list_complete: true;
 };
 /**
- * Minimal structural projection of `VectorizeIndex` so unit tests can pass a
+ * Minimal structural projection of `Vectorize` so unit tests can pass a
  * plain-object double and the real Cloudflare binding satisfies the same shape.
  * Mirrors the surface documented at
  * https://developers.cloudflare.com/vectorize/reference/client-api/.
+ *
+ * **Method** syntax, not arrow properties: `ReadonlyArray` is the correct (wider)
+ * parameter type, but an arrow property makes parameters strictly contravariant
+ * under `strictFunctionTypes`, and Cloudflare declares `deleteByIds(ids: string[])`
+ * — so the real binding did not satisfy this interface at all. Methods are checked
+ * bivariantly, which admits both it and a `readonly`-clean double.
+ * `binding-assignability.test-d.ts` in `@lunora/bindings` pins that against the
+ * published types. `this: void` keeps the members usable as bare references, which
+ * is what every `expect(double.query)` assertion in those tests does.
  */
 interface VectorizeIndexLike {
-  deleteByIds: (ids: ReadonlyArray<string>) => Promise<VectorizeDeleteMutation>;
-  describe?: () => Promise<VectorizeIndexDetails>;
-  getByIds: (ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorizeVector>>;
-  insert: (vectors: ReadonlyArray<VectorizeVector>) => Promise<VectorizeUpsertMutation>;
-  query: (vector: ReadonlyArray<number>, options?: VectorizeQueryOptions) => Promise<VectorizeMatches>;
-  upsert: (vectors: ReadonlyArray<VectorizeVector>) => Promise<VectorizeUpsertMutation>;
+  deleteByIds(this: void, ids: ReadonlyArray<string>): Promise<VectorizeDeleteMutation>;
+  describe?(this: void): Promise<VectorizeIndexDetails>;
+  getByIds(this: void, ids: ReadonlyArray<string>): Promise<ReadonlyArray<VectorizeVector>>;
+  insert(this: void, vectors: ReadonlyArray<VectorizeVector>): Promise<VectorizeUpsertMutation>;
+  query(this: void, vector: VectorValues, options?: VectorizeQueryOptions): Promise<VectorizeMatches>;
+  upsert(this: void, vectors: ReadonlyArray<VectorizeVector>): Promise<VectorizeUpsertMutation>;
 }
 type VectorMetric = "cosine" | "euclidean" | "dot-product";
+/**
+ * An embedding, as either a plain array or one of the typed arrays Vectorize
+ * accepts. The typed-array arms are not a convenience: Cloudflare's own
+ * `VectorizeVector.values` is `VectorFloatArray | number[]`, so a projection
+ * limited to `ReadonlyArray<number>` excluded every vector the real binding
+ * returns. Read one with `Array.from(...)` rather than an array method.
+ */
+type VectorValues = Float32Array | Float64Array | ReadonlyArray<number>;
 interface VectorizeVector {
   id: string;
   metadata?: Record<string, unknown>;
   namespace?: string;
-  values: ReadonlyArray<number>;
+  values: VectorValues;
 }
+/**
+ * Query options, kept a superset of Cloudflare's own `VectorizeQueryOptions` so
+ * the real binding satisfies {@link VectorizeIndexLike}. `returnMetadata` carries
+ * the legacy `boolean` arm for that reason - pass one of the three levels; the
+ * boolean is what Cloudflare still accepts, not what callers should write.
+ */
 interface VectorizeQueryOptions {
   filter?: Record<string, unknown>;
   namespace?: string;
-  returnMetadata?: "none" | "indexed" | "all";
+  returnMetadata?: "none" | "indexed" | "all" | boolean;
   returnValues?: boolean;
   topK?: number;
 }
@@ -324,7 +347,7 @@ interface VectorizeMatch {
   metadata?: Record<string, unknown>;
   namespace?: string;
   score: number;
-  values?: ReadonlyArray<number>;
+  values?: VectorValues;
 }
 interface VectorizeMatches {
   count: number;
@@ -337,11 +360,24 @@ interface VectorizeDeleteMutation {
   count?: number;
   mutationId: string;
 }
+/**
+ * What `describe()` reports. Both spellings of the row count are optional because
+ * Cloudflare renamed it between API generations — the beta `VectorizeIndex`
+ * returns `vectorsCount`, the current `Vectorize` returns `vectorCount` — and a
+ * projection that required either one excluded a real binding. Read them as
+ * `vectorCount ?? vectorsCount`.
+ *
+ * `processedUpTo*` are typed loosely for the same reason: documented as ISO 8601
+ * strings, typed as `number` in `@cloudflare/workers-types`.
+ */
 interface VectorizeIndexDetails {
   dimensions: number;
-  processedUpToDatetime?: string;
-  processedUpToMutation?: string;
-  vectorsCount: number;
+  processedUpToDatetime?: number | string;
+  processedUpToMutation?: number | string;
+  /** The current `Vectorize.describe()` spelling. */
+  vectorCount?: number;
+  /** The beta `VectorizeIndex.describe()` spelling. */
+  vectorsCount?: number;
 }
 /**
  * A single-range read against R2: an `{ offset, length }` window (at least one
@@ -906,4 +942,4 @@ export { type AnalyticsEngineDataPoint, type AnalyticsEngineDataPointLike, type
  * workerd, Node). It is intended to be the leaf dependency every other
  * `@lunora/*` package can import without creating cycles.
  */
-type ExecutionContextLike, type HttpCacheLike, type HttpCacheQueryOptions, type KVNamespaceLike, type KvGetOptions, type KvListKey, type KvNamespaceListResult, type KvNamespacePutOptions, type KvValue, type KvValueType, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, NODE_CAPABILITIES, NOOP_EXECUTION_CONTEXT, type PlatformCapabilities, type QueueBindingLike, type QueueContentType, type QueueMessageLike, type QueueRetryOptions, type QueueSendBatchOptions, type QueueSendOptions, type QueueSendOptionsLike, type QueueSendRequestLike, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2UploadedPartLike, type VectorMatchLike, type VectorMetric, type VectorRecordLike, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector };
+type ExecutionContextLike, type HttpCacheLike, type HttpCacheQueryOptions, type KVNamespaceLike, type KvGetOptions, type KvListKey, type KvNamespaceListResult, type KvNamespacePutOptions, type KvValue, type KvValueType, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, NODE_CAPABILITIES, NOOP_EXECUTION_CONTEXT, type PlatformCapabilities, type QueueBindingLike, type QueueContentType, type QueueMessageLike, type QueueRetryOptions, type QueueSendBatchOptions, type QueueSendOptions, type QueueSendOptionsLike, type QueueSendRequestLike, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2UploadedPartLike, type VectorMatchLike, type VectorMetric, type VectorRecordLike, type VectorValues, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/platform",
-  "version": "1.0.0-alpha.27",
+  "version": "1.0.0-alpha.28",
   "description": "Provider-neutral host contracts for Lunora: shard/socket/directory/scheduler interfaces, binding projections, and the platform capability matrix",
   "keywords": [
     "cloudflare",