@pylonsync/sdk 0.22.43 → 0.22.44

package/dist/index.d.ts

@@ -367,6 +367,11 @@ export interface EntityDefinition {
      * in the audit log as `retention.delete`. See {@link RetentionRule}.
      */
     retention?: RetentionRule;
+    /**
+     * Run an internal function after edits to a row land. See
+     * {@link AfterEditHook}.
+     */
+    afterEdit?: AfterEditHook;
     /**
      * Per-row CRDT (Loro) documents. Default `true`: every write merges through
      * a document, and offline edits from several devices converge. Set `false`
@@ -427,6 +432,27 @@ export interface RetentionRule {
     after?: string;
     hold?: string;
 }
+/**
+ * An internal function that runs after edits to a row land: a search index,
+ * a preview, a review queue.
+ *
+ * ```ts
+ * entity("Document", { … }, { afterEdit: { fn: "indexDocument", delaySeconds: 5 } })
+ * ```
+ *
+ * Any committed write to a row (an insert, an update, a live edit, a
+ * delete) schedules `fn` with `{ id }`, to run at the end of the row's
+ * current `delaySeconds` window; every edit in that window shares the run.
+ * A row edited without pause gets one run per window. `fn` must be
+ * `internal: true`; it runs without a user, like a cron target, and reads
+ * the row itself (it may have been deleted). Runs are jobs: they survive a
+ * restart, retry on failure, and show in `pylon jobs`.
+ */
+export interface AfterEditHook {
+    fn: string;
+    /** The window, in seconds. Default 5. */
+    delaySeconds?: number;
+}
 export declare function entity(name: string, fields: Record<string, FieldBuilder>, options?: {
     indexes?: IndexDefinition[];
     relations?: RelationDefinition[];
@@ -444,6 +470,9 @@ export declare function entity(name: string, fields: Record<string, FieldBuilder
     /** Delete rows past a retention period. Mirrors
      *  {@link EntityDefinition.retention}. */
     retention?: RetentionRule;
+    /** Run an internal function after edits land. Mirrors
+     *  {@link EntityDefinition.afterEdit}. */
+    afterEdit?: AfterEditHook;
 }): EntityDefinition;
 export declare function relation(def: RelationDefinition): RelationDefinition;
 export { defineRoute } from "./route";
@@ -635,6 +664,11 @@ export interface ManifestEntity {
     audit?: boolean;
     /** Retention rule; omitted when unset. */
     retention?: RetentionRule;
+    /** After-edit hook; omitted when unset. */
+    after_edit?: {
+        function: string;
+        delay_secs: number;
+    };
 }
 export interface ManifestRoute {
     path: string;

package/package.json

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

package/src/entity-after-edit.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { entitiesToManifest, entity, field } from "./index";
+
+describe("entity afterEdit option", () => {
+  test("reaches the manifest as after_edit, with the default window", () => {
+    const [a, b] = entitiesToManifest([
+      entity("Doc", { title: field.string() }, { afterEdit: { fn: "indexDoc" } }),
+      entity("Note", { title: field.string() }, { afterEdit: { fn: "indexNote", delaySeconds: 30 } }),
+    ]);
+    expect(a.after_edit).toEqual({ function: "indexDoc", delay_secs: 5 });
+    expect(b.after_edit).toEqual({ function: "indexNote", delay_secs: 30 });
+  });
+
+  test("is omitted when unset", () => {
+    const [m] = entitiesToManifest([entity("Doc", { title: field.string() })]);
+    expect("after_edit" in m).toBe(false);
+  });
+
+  test("refuses a window that is not a whole number of seconds, and a missing function", () => {
+    for (const delaySeconds of [0, 1.5, -1]) {
+      expect(() =>
+        entitiesToManifest([entity("Doc", { t: field.string() }, { afterEdit: { fn: "f", delaySeconds } })]),
+      ).toThrow("whole number of seconds");
+    }
+    expect(() => entitiesToManifest([entity("Doc", { t: field.string() }, { afterEdit: { fn: "" } })])).toThrow(
+      "afterEdit needs fn",
+    );
+  });
+});

package/src/index.ts

@@ -476,6 +476,11 @@ export interface EntityDefinition {
    * in the audit log as `retention.delete`. See {@link RetentionRule}.
    */
   retention?: RetentionRule;
+  /**
+   * Run an internal function after edits to a row land. See
+   * {@link AfterEditHook}.
+   */
+  afterEdit?: AfterEditHook;
   /**
    * Per-row CRDT (Loro) documents. Default `true`: every write merges through
    * a document, and offline edits from several devices converge. Set `false`
@@ -539,6 +544,28 @@ export interface RetentionRule {
   hold?: string;
 }
 
+/**
+ * An internal function that runs after edits to a row land: a search index,
+ * a preview, a review queue.
+ *
+ * ```ts
+ * entity("Document", { … }, { afterEdit: { fn: "indexDocument", delaySeconds: 5 } })
+ * ```
+ *
+ * Any committed write to a row (an insert, an update, a live edit, a
+ * delete) schedules `fn` with `{ id }`, to run at the end of the row's
+ * current `delaySeconds` window; every edit in that window shares the run.
+ * A row edited without pause gets one run per window. `fn` must be
+ * `internal: true`; it runs without a user, like a cron target, and reads
+ * the row itself (it may have been deleted). Runs are jobs: they survive a
+ * restart, retry on failure, and show in `pylon jobs`.
+ */
+export interface AfterEditHook {
+  fn: string;
+  /** The window, in seconds. Default 5. */
+  delaySeconds?: number;
+}
+
 export function entity(
   name: string,
   fields: Record<string, FieldBuilder>,
@@ -559,6 +586,9 @@ export function entity(
     /** Delete rows past a retention period. Mirrors
      *  {@link EntityDefinition.retention}. */
     retention?: RetentionRule;
+    /** Run an internal function after edits land. Mirrors
+     *  {@link EntityDefinition.afterEdit}. */
+    afterEdit?: AfterEditHook;
   },
 ): EntityDefinition {
   return {
@@ -571,6 +601,7 @@ export function entity(
     crdt: options?.crdt,
     audit: options?.audit,
     retention: options?.retention,
+    afterEdit: options?.afterEdit,
   };
 }
 
@@ -822,6 +853,8 @@ export interface ManifestEntity {
   audit?: boolean;
   /** Retention rule; omitted when unset. */
   retention?: RetentionRule;
+  /** After-edit hook; omitted when unset. */
+  after_edit?: { function: string; delay_secs: number };
 }
 
 export interface ManifestRoute {
@@ -1376,6 +1409,14 @@ export function entitiesToManifest(
         ...(e.retention.hold ? { hold: e.retention.hold } : {}),
       };
     }
+    if (e.afterEdit) {
+      const delay = e.afterEdit.delaySeconds ?? 5;
+      if (!e.afterEdit.fn) throw new Error(`${e.name}: afterEdit needs fn`);
+      if (!Number.isInteger(delay) || delay < 1) {
+        throw new Error(`${e.name}: afterEdit.delaySeconds must be a whole number of seconds, at least 1`);
+      }
+      result.after_edit = { function: e.afterEdit.fn, delay_secs: delay };
+    }
     return result;
   });
 }