@pylonsync/sdk 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -74,6 +74,14 @@ export interface FieldDefinition {
      * `serverOnly`, which hides a field from ALL client surfaces.
      */
     syncOmit?: boolean;
+    /**
+     * Longest value the field accepts, in characters (Unicode code
+     * points). Set with `field.string().max(n)` or
+     * `field.richtext().max(n)`. The server rejects a longer value with
+     * `FIELD_TOO_LONG` on every write path: the entity API, sync push,
+     * `ctx.db` in functions, and collaborative (CRDT) edits.
+     */
+    maxLength?: number;
     /**
      * When true, the field is **set on insert but cannot be changed
      * by client updates**. The framework rejects any `PATCH`/`PUT`
@@ -162,6 +170,15 @@ interface FieldBuilder {
      * editor still gets it via `db.get("Variant", id)`.
      */
     syncOmit(): FieldBuilder;
+    /**
+     * Cap the value at `n` characters (Unicode code points). String and
+     * richtext fields only. See [`FieldDefinition.maxLength`].
+     *
+     * Example: `bio: field.string().max(280)` stops any client, guests
+     * included, from storing a longer bio that every other client would
+     * then sync.
+     */
+    max(n: number): FieldBuilder;
     /**
      * Mark the field as set-on-insert-only. See [`FieldDefinition.readonly`]
      * for the full semantics.
@@ -543,6 +560,9 @@ export interface ManifestField {
     /** Set when the field is `field.X().syncOmit()` — see
      *  [`FieldDefinition.syncOmit`]. Omitted by default. */
     syncOmit?: boolean;
+    /** Set by `.max(n)` — see [`FieldDefinition.maxLength`]. Omitted when
+     *  the field has no limit. */
+    maxLength?: number;
     /** Set when the field is `field.X().readonly()` — see
      *  [`FieldDefinition.readonly`]. Omitted by default. */
     readonly?: boolean;

package/package.json

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

package/src/field-max-length.test.ts

@@ -0,0 +1,39 @@
+/**
+ * `field.string().max(n)` manifest contract:
+ *   - the limit serializes as `maxLength` (the Rust `ManifestField`
+ *     reads that key), and only when set
+ *   - it composes with the other modifiers in any order
+ *   - it is refused on non-text fields and for non-positive limits
+ */
+import { expect, test } from "bun:test";
+import { entitiesToManifest, field } from "./index";
+
+test(".max(n) serializes as maxLength on string and richtext fields", () => {
+  const [ent] = entitiesToManifest([
+    {
+      name: "Post",
+      fields: {
+        title: field.string().max(120),
+        body: field.richtext().optional().max(20_000),
+        status: field.enum(["draft", "live"]).max(5),
+        slug: field.string(),
+      },
+    },
+  ]);
+  const byName = (n: string) => ent.fields.find((f) => f.name === n)!;
+  expect(byName("title").maxLength).toBe(120);
+  expect(byName("body").maxLength).toBe(20_000);
+  expect(byName("body").optional).toBe(true);
+  expect(byName("status").maxLength).toBe(5);
+  // No limit, no key: unannotated manifests are unchanged.
+  expect("maxLength" in byName("slug")).toBe(false);
+});
+
+test(".max(n) is refused on other field types and for bad limits", () => {
+  expect(() => (field.int() as { max(n: number): unknown }).max(5)).toThrow(/field.string/);
+  expect(() => field.json().max(5)).toThrow(/field.string/);
+  expect(() => field.string().max(0)).toThrow(/positive integer/);
+  expect(() => field.string().max(1.5)).toThrow(/positive integer/);
+  expect(() => field.string().max(-1)).toThrow(/positive integer/);
+  expect(() => field.string().max(1)).not.toThrow();
+});

package/src/index.ts

@@ -101,6 +101,14 @@ export interface FieldDefinition {
    * `serverOnly`, which hides a field from ALL client surfaces.
    */
   syncOmit?: boolean;
+  /**
+   * Longest value the field accepts, in characters (Unicode code
+   * points). Set with `field.string().max(n)` or
+   * `field.richtext().max(n)`. The server rejects a longer value with
+   * `FIELD_TOO_LONG` on every write path: the entity API, sync push,
+   * `ctx.db` in functions, and collaborative (CRDT) edits.
+   */
+  maxLength?: number;
   /**
    * When true, the field is **set on insert but cannot be changed
    * by client updates**. The framework rejects any `PATCH`/`PUT`
@@ -190,6 +198,15 @@ interface FieldBuilder {
    * editor still gets it via `db.get("Variant", id)`.
    */
   syncOmit(): FieldBuilder;
+  /**
+   * Cap the value at `n` characters (Unicode code points). String and
+   * richtext fields only. See [`FieldDefinition.maxLength`].
+   *
+   * Example: `bio: field.string().max(280)` stops any client, guests
+   * included, from storing a longer bio that every other client would
+   * then sync.
+   */
+  max(n: number): FieldBuilder;
   /**
    * Mark the field as set-on-insert-only. See [`FieldDefinition.readonly`]
    * for the full semantics.
@@ -273,6 +290,17 @@ function buildField(def: FieldDefinition): FieldBuilder {
     syncOmit() {
       return buildField({ ...def, syncOmit: true });
     },
+    max(n: number) {
+      if (def.type !== "string" && def.type !== "richtext") {
+        throw new Error(
+          `.max(n) applies to field.string() and field.richtext(), not ${def.type}`,
+        );
+      }
+      if (!Number.isInteger(n) || n < 1 || n > 0xffffffff) {
+        throw new Error(`.max(n): n must be a positive integer, got ${n}`);
+      }
+      return buildField({ ...def, maxLength: n });
+    },
     readonly() {
       return buildField({ ...def, readonly: true });
     },
@@ -715,6 +743,9 @@ export interface ManifestField {
   /** Set when the field is `field.X().syncOmit()` — see
    *  [`FieldDefinition.syncOmit`]. Omitted by default. */
   syncOmit?: boolean;
+  /** Set by `.max(n)` — see [`FieldDefinition.maxLength`]. Omitted when
+   *  the field has no limit. */
+  maxLength?: number;
   /** Set when the field is `field.X().readonly()` — see
    *  [`FieldDefinition.readonly`]. Omitted by default. */
   readonly?: boolean;
@@ -1240,6 +1271,9 @@ export function entitiesToManifest(
         if (fb._def.syncOmit) {
           f.syncOmit = true;
         }
+        if (fb._def.maxLength !== undefined) {
+          f.maxLength = fb._def.maxLength;
+        }
         if (fb._def.readonly) {
           f.readonly = true;
         }
@@ -2327,6 +2361,9 @@ function agentEntities(): EntityDefinition[] {
         // Cumulative model↔tool round-trips across every invocation of
         // this run. `maxSteps` bounds one invocation, not this.
         steps: field.int().optional(),
+        // What server code passed as `context` to ctx.agents.run; the
+        // tools receive it as `run.context`. Written by server code only.
+        context: field.json().optional(),
         createdAt: field.datetime(),
         updatedAt: field.datetime(),
       },