@pylonsync/sdk 0.4.19 → 0.4.20

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type RouteMode = "static" | "server" | "live" | "ssr";
-export type FieldType = "string" | "int" | "float" | "bool" | "datetime" | "richtext" | "json" | `id(${string})`;
+export type FieldType = "string" | "int" | "float" | "bool" | "datetime" | "richtext" | "json" | `id(${string})` | `vector(${number})`;
 /**
  * CRDT container override for a field. Wire format is the kebab-case
  * string each variant maps to (`"text"`, `"counter"`, `"movable-list"`,
@@ -243,6 +243,19 @@ export declare const field: {
      */
     json: () => FieldBuilder;
     id: (target: string) => FieldBuilder;
+    /**
+     * `field.vector(1536)` — a fixed-dimension embedding, written as
+     * `number[]` and stored as a packed float array (BLOB in SQLite,
+     * BYTEA in Postgres). Query it with `ctx.db.vectorSearch(entity,
+     * { field, vector, limit })` — exact nearest-neighbor, cosine by
+     * default.
+     *
+     * Vector fields are always server-only: a 1536-dim embedding is
+     * 6KB+ per row and belongs to server-side retrieval, not client
+     * replicas or HTTP responses. Inserts/updates validate the exact
+     * dimension count and reject NaN/Infinity elements.
+     */
+    vector: (dims: number) => FieldBuilder;
     /**
      * `field.enum(["pending", "paid", "failed"])` — stored as a string with
      * allowed-values metadata so codegen emits a precise literal union

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.19",
+  "version": "0.4.20",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -16,7 +16,8 @@ export type FieldType =
   | "datetime"
   | "richtext"
   | "json"
-  | `id(${string})`;
+  | `id(${string})`
+  | `vector(${number})`;
 
 // ---------------------------------------------------------------------------
 // Field builder
@@ -318,6 +319,26 @@ export const field = {
    */
   json: () => createFieldBuilder("json"),
   id: (target: string) => createFieldBuilder(`id(${target})`),
+  /**
+   * `field.vector(1536)` — a fixed-dimension embedding, written as
+   * `number[]` and stored as a packed float array (BLOB in SQLite,
+   * BYTEA in Postgres). Query it with `ctx.db.vectorSearch(entity,
+   * { field, vector, limit })` — exact nearest-neighbor, cosine by
+   * default.
+   *
+   * Vector fields are always server-only: a 1536-dim embedding is
+   * 6KB+ per row and belongs to server-side retrieval, not client
+   * replicas or HTTP responses. Inserts/updates validate the exact
+   * dimension count and reject NaN/Infinity elements.
+   */
+  vector: (dims: number) => {
+    if (!Number.isInteger(dims) || dims < 1 || dims > 8192) {
+      throw new Error(
+        `field.vector(dims): dims must be an integer in 1..8192, got ${dims}`
+      );
+    }
+    return createFieldBuilder(`vector(${dims})`);
+  },
   /**
    * `field.enum(["pending", "paid", "failed"])` — stored as a string with
    * allowed-values metadata so codegen emits a precise literal union
@@ -970,7 +991,9 @@ export function entitiesToManifest(
         if (fb._def.crdt !== undefined) {
           f.crdt = fb._def.crdt;
         }
-        if (fb._def.serverOnly) {
+        if (fb._def.serverOnly || fb._def.type.startsWith("vector(")) {
+          // Vector fields are unconditionally server-only: multi-KB
+          // embeddings must never ride the sync stream or HTTP reads.
           f.serverOnly = true;
         }
         if (fb._def.syncOmit) {

package/src/vector-field.test.ts

@@ -0,0 +1,36 @@
+/**
+ * `field.vector(dims)` manifest contract:
+ *   - the wire type string is `vector(<dims>)`
+ *   - vector fields serialize with `serverOnly: true` unconditionally
+ *     (multi-KB embeddings must never enter sync or HTTP reads)
+ *   - dims outside 1..8192 throw at schema-definition time
+ */
+import { expect, test } from "bun:test";
+import { entitiesToManifest, field } from "./index";
+
+test("field.vector serializes as vector(dims) with forced serverOnly", () => {
+  const [ent] = entitiesToManifest([
+    {
+      name: "Doc",
+      fields: {
+        title: field.string(),
+        embedding: field.vector(1536).optional(),
+      },
+    },
+  ]);
+  const emb = ent.fields.find((f) => f.name === "embedding")!;
+  expect(emb.type).toBe("vector(1536)");
+  expect(emb.optional).toBe(true);
+  expect(emb.serverOnly).toBe(true);
+  // Non-vector fields don't inherit the forcing.
+  const title = ent.fields.find((f) => f.name === "title")!;
+  expect(title.serverOnly).toBeUndefined();
+});
+
+test("field.vector rejects out-of-range dims", () => {
+  expect(() => field.vector(0)).toThrow();
+  expect(() => field.vector(1.5)).toThrow();
+  expect(() => field.vector(8193)).toThrow();
+  expect(() => field.vector(8192)).not.toThrow();
+  expect(() => field.vector(1)).not.toThrow();
+});