@triggerlink/sdk 0.5.1 → 0.6.0

package/README.md

@@ -57,6 +57,28 @@ client.register("http://localhost:3000/api/triggerlink"); // requires eventKey
 
 Note: for local development, point the serve URL at `http://localhost:3000/api/triggerlink`; after changing functions in the app, call `POST /api/v1/apps/sync {"url":"..."}` to sync — no platform restart needed.
 
+## Flow control (debounce / throttle / batch)
+
+Three optional knobs on `createFunction`; durations accept a Go duration string (`"5m"`) or a millisecond number.
+
+```ts
+// Collapse a burst of edits into one run, keeping the last event
+createFunction({ id: "index-doc", event: "doc/changed",
+  debounce: { period: "5m", key: "data.doc_id", timeout: "1h" } }, handler);
+
+// At most 10 runs start per minute per tenant; over-limit runs are delayed, not dropped
+createFunction({ id: "call-api", event: "api/call",
+  throttle: { limit: 10, period: "1m", key: "data.tenant" } }, handler);
+
+// Trigger once per 100 events (or every 30s), receiving the whole batch
+createFunction({ id: "bulk-index", event: "doc/changed",
+  batch: { maxSize: 100, timeout: "30s" } }, async (ctx) => {
+    for (const e of ctx.events ?? []) { /* arrival order; ctx.event is the first */ }
+  });
+```
+
+`key` is an expr-lang expression over `data` that groups events into independent windows/quotas. Debounce and batch both act at the routing layer — configuring both makes debounce win. See the User Guide section 5.3.8 for the full semantics.
+
 ## Constraints (same as the Go SDK; see protocol section 6)
 
 - Side effects must go inside `step.run`; the function is re-invoked from the start on every callback, so code outside steps runs repeatedly;

package/dist/function.d.ts

@@ -18,6 +18,11 @@ export interface CancelOnRule {
 /** 传给用户 handler 的上下文。 */
 export interface HandlerContext<T = unknown> {
     event: EventPayload<T>;
+    /**
+     * 批触发（FR-4.7，函数配了 batch）时给出整批事件，按到达顺序；此时 event 是其首条。
+     * 普通触发下不存在该字段。
+     */
+    events?: EventPayload<T>[];
     step: StepTool;
     runId: string;
     attempt: number;
@@ -30,6 +35,33 @@ export interface RunFailedEventData {
     /** 触发该 run 的原始事件 */
     event: EventPayload;
 }
+/** 防抖配置（FR-4.5）。时长可写 Go duration 字符串（"5m"）或毫秒数（300000）。 */
+export interface DebounceOpts {
+    /** 合并窗口：窗口内每来一个新事件就把触发时间推后一个 period */
+    period: string | number;
+    /** 可选 expr 表达式（环境只含 data），按其求值结果分组；留空 = 整个函数共用一个窗口 */
+    key?: string;
+    /** 距首个事件的最长延迟，给持续刷新的窗口封顶；缺省 = 不封顶 */
+    timeout?: string | number;
+}
+/** 限流配置（FR-4.4）。超限的 run 不丢弃，延迟到下一窗口。 */
+export interface ThrottleOpts {
+    /** 每个窗口内允许启动的 run 数 */
+    limit: number;
+    /** 窗口长度 */
+    period: string | number;
+    /** 可选 expr 表达式（环境只含 data），按其求值结果分组 */
+    key?: string;
+}
+/** 批处理配置（FR-4.7）。攒够 maxSize 或距首条超过 timeout 即以事件数组触发一个 run。 */
+export interface BatchOpts {
+    /** 单批最大事件数，随 manifest 上报为 max_size */
+    maxSize: number;
+    /** 距首条事件的最长等待；攒不满时由它兜底 flush */
+    timeout: string | number;
+    /** 可选 expr 表达式（环境只含 data），按其求值结果分组 */
+    key?: string;
+}
 export interface FunctionOpts {
     /** 稳定标识，改名会丢历史 memo 关联 */
     id: string;
@@ -49,6 +81,12 @@ export interface FunctionOpts {
      * 并发 triggerlink/run.failed 事件——配置了 onFailure 的函数会因此触发。缺省 = 不限时。
      */
     timeout?: string | number;
+    /** 防抖（FR-4.5），随 manifest 上报为 debounce。与 batch 同为路由层流控，同时配置时以 debounce 为准 */
+    debounce?: DebounceOpts;
+    /** 限流（FR-4.4），随 manifest 上报为 throttle */
+    throttle?: ThrottleOpts;
+    /** 批处理（FR-4.7），随 manifest 上报为 batch */
+    batch?: BatchOpts;
     /**
      * run 进入 Failed 终态时的处理器（FR-2.11）。serve 时注册隐式函数 <id>/on-failure，
      * 订阅内部事件 triggerlink/run.failed（match 按 function_id 过滤），handler 内可用全部 step 原语。

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createClient, type Client, type ClientOptions, type SendEventInput, type SendResult, type RegisterOptions, } from "./client.js";
-export { createFunction, type TriggerFunction, type FunctionOpts, type HandlerContext, type EventPayload, type TriggerLinkEvent, type CancelOnRule, type RunFailedEventData, } from "./function.js";
+export { createFunction, type TriggerFunction, type FunctionOpts, type HandlerContext, type EventPayload, type TriggerLinkEvent, type CancelOnRule, type RunFailedEventData, type DebounceOpts, type ThrottleOpts, type BatchOpts, } from "./function.js";
 export { serve, sdkVersion, type ServeOptions } from "./serve.js";
 export { StepInterrupt, type Opcode, type StepState, type OutgoingEvent } from "./execx.js";
 export type { StepTool, WaitForEventOpts } from "./step.js";

package/dist/serve.js

@@ -24,6 +24,10 @@ export function serve(opts) {
             });
         }
     }
+    /** 流控配置的时长字段：毫秒数转 Go duration 字符串，字符串原样透传（协议要求 Go duration）。 */
+    function goDuration(v) {
+        return typeof v === "number" ? msToGoDuration(v, "createFunction") : v;
+    }
     async function GET(req) {
         if (!verifySignature(opts.client.signingKey, req.headers.get(SIGNATURE_HEADER), new Uint8Array(0))) {
             return json({ error: "unauthorized" }, 401);
@@ -47,6 +51,33 @@ export function serve(opts) {
                             : f.opts.timeout,
                     }
                     : {}),
+                ...(f.opts.debounce
+                    ? {
+                        debounce: {
+                            period: goDuration(f.opts.debounce.period),
+                            ...(f.opts.debounce.key ? { key: f.opts.debounce.key } : {}),
+                            ...(f.opts.debounce.timeout ? { timeout: goDuration(f.opts.debounce.timeout) } : {}),
+                        },
+                    }
+                    : {}),
+                ...(f.opts.throttle
+                    ? {
+                        throttle: {
+                            limit: f.opts.throttle.limit,
+                            period: goDuration(f.opts.throttle.period),
+                            ...(f.opts.throttle.key ? { key: f.opts.throttle.key } : {}),
+                        },
+                    }
+                    : {}),
+                ...(f.opts.batch
+                    ? {
+                        batch: {
+                            max_size: f.opts.batch.maxSize,
+                            timeout: goDuration(f.opts.batch.timeout),
+                            ...(f.opts.batch.key ? { key: f.opts.batch.key } : {}),
+                        },
+                    }
+                    : {}),
             })),
         });
     }
@@ -73,6 +104,7 @@ export function serve(opts) {
         try {
             const output = await fn.handler({
                 event: cbReq.ctx.event,
+                ...(cbReq.ctx.events ? { events: cbReq.ctx.events } : {}),
                 step,
                 runId: cbReq.ctx.run_id,
                 attempt: cbReq.ctx.attempt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triggerlink/sdk",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "TriggerLink TypeScript SDK: durable, crash-recoverable functions for Next.js / Node.js",
   "keywords": [
     "triggerlink",