@smthrs/triggers 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Trigger.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Durable trigger declarations.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Schedule from "./Schedule.ts";
+import { type TriggerError } from "./TriggerError.ts";
+/**
+ * How a trigger behaves when an occurrence arrives while its previous run
+ * is still going.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Overlap: Schema.Literals<readonly ["skip", "buffer-one", "supersede"]>;
+/**
+ * The decoded form of {@link Overlap}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Overlap = Schedule.Overlap;
+/**
+ * How many missed occurrences a trigger owes after downtime.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const CatchUp: Schema.Literals<readonly ["none", "one", "all"]>;
+/**
+ * The decoded form of {@link CatchUp}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CatchUp = Schedule.CatchUp;
+/**
+ * A trigger declaration: which flow to run, with what input, on what
+ * schedule.
+ *
+ * `input` is JSON rather than `unknown` because the store persists it with
+ * `JSON.stringify` into a `NOT NULL` column. The schema refuses `undefined`,
+ * `NaN`, a `Date`, and functions at the declaration boundary.
+ * Enumerable getters are accepted when their values are JSON. They are
+ * evaluated during decoding and again during SQL serialization. Every store
+ * takes an eager serialized snapshot before returning its Effect; use plain
+ * JSON values for stable input across reads.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Trigger: Schema.Struct<{
+    readonly enabled: Schema.Boolean;
+    readonly cron: Schema.NonEmptyString;
+    readonly timezone: Schema.optional<Schema.NonEmptyString>;
+    readonly overlap: Schema.withDecodingDefault<Schema.Literals<readonly ["skip", "buffer-one", "supersede"]>, never>;
+    readonly catchUp: Schema.withDecodingDefault<Schema.Literals<readonly ["none", "one", "all"]>, never>;
+    readonly maxCatchUp: Schema.withDecodingDefault<Schema.Int, never>;
+    readonly id: Schema.NonEmptyString;
+    readonly flowId: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * The decoded form of {@link Trigger}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Trigger = typeof Trigger.Type;
+/**
+ * Decodes and validates a trigger declaration.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (input: unknown) => Effect.Effect<Trigger, TriggerError>;
+//# sourceMappingURL=Trigger.d.ts.map

package/dist/esm/Trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Trigger.d.ts","sourceRoot":"","sources":["../../src/Trigger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,+DAAmB,CAAA;AACvC;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;AACtC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,kDAAmB,CAAA;AACvC;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;AAEtC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;EAMlB,CAAA;AACF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAItE,CAAA"}

package/dist/esm/Trigger.js

@@ -0,0 +1,56 @@
+/**
+ * Durable trigger declarations.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Schedule from "./Schedule.js";
+import { fromSchemaError } from "./TriggerError.js";
+/**
+ * How a trigger behaves when an occurrence arrives while its previous run
+ * is still going.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Overlap = Schedule.Overlap;
+/**
+ * How many missed occurrences a trigger owes after downtime.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const CatchUp = Schedule.CatchUp;
+/**
+ * A trigger declaration: which flow to run, with what input, on what
+ * schedule.
+ *
+ * `input` is JSON rather than `unknown` because the store persists it with
+ * `JSON.stringify` into a `NOT NULL` column. The schema refuses `undefined`,
+ * `NaN`, a `Date`, and functions at the declaration boundary.
+ * Enumerable getters are accepted when their values are JSON. They are
+ * evaluated during decoding and again during SQL serialization. Every store
+ * takes an eager serialized snapshot before returning its Effect; use plain
+ * JSON values for stable input across reads.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Trigger = Schema.Struct({
+    id: Schema.NonEmptyString,
+    flowId: Schema.NonEmptyString,
+    input: Schema.Json,
+    ...Schedule.Schedule.fields,
+    enabled: Schema.Boolean
+});
+/**
+ * Decodes and validates a trigger declaration.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (input) => Schema.decodeUnknownEffect(Trigger)(input).pipe(Effect.mapError((cause) => fromSchemaError("invalid_trigger", "Trigger declaration is invalid", cause)), Effect.flatMap(Schedule.validate));
+//# sourceMappingURL=Trigger.js.map

package/dist/esm/Trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Trigger.js","sourceRoot":"","sources":["../../src/Trigger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,eAAe,EAAqB,MAAM,mBAAmB,CAAA;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;AAQvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;AASvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,MAAM,CAAC,cAAc;IACzB,MAAM,EAAE,MAAM,CAAC,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC,IAAI;IAClB,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM;IAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;CACxB,CAAC,CAAA;AASF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAwC,EAAE,CAC3E,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAC7C,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,iBAAiB,EAAE,gCAAgC,EAAE,KAAK,CAAC,CAAC,EACvG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAClC,CAAA","sourcesContent":["/**\n * Durable trigger declarations.\n *\n * @see packages/smithers/agent/triggers/docs/api.md\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as Schedule from \"./Schedule.ts\"\nimport { fromSchemaError, type TriggerError } from \"./TriggerError.ts\"\n\n/**\n * How a trigger behaves when an occurrence arrives while its previous run\n * is still going.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Overlap = Schedule.Overlap\n/**\n * The decoded form of {@link Overlap}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Overlap = Schedule.Overlap\n/**\n * How many missed occurrences a trigger owes after downtime.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const CatchUp = Schedule.CatchUp\n/**\n * The decoded form of {@link CatchUp}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type CatchUp = Schedule.CatchUp\n\n/**\n * A trigger declaration: which flow to run, with what input, on what\n * schedule.\n *\n * `input` is JSON rather than `unknown` because the store persists it with\n * `JSON.stringify` into a `NOT NULL` column. The schema refuses `undefined`,\n * `NaN`, a `Date`, and functions at the declaration boundary.\n * Enumerable getters are accepted when their values are JSON. They are\n * evaluated during decoding and again during SQL serialization. Every store\n * takes an eager serialized snapshot before returning its Effect; use plain\n * JSON values for stable input across reads.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Trigger = Schema.Struct({\n  id: Schema.NonEmptyString,\n  flowId: Schema.NonEmptyString,\n  input: Schema.Json,\n  ...Schedule.Schedule.fields,\n  enabled: Schema.Boolean\n})\n/**\n * The decoded form of {@link Trigger}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Trigger = typeof Trigger.Type\n\n/**\n * Decodes and validates a trigger declaration.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (input: unknown): Effect.Effect<Trigger, TriggerError> =>\n  Schema.decodeUnknownEffect(Trigger)(input).pipe(\n    Effect.mapError((cause) => fromSchemaError(\"invalid_trigger\", \"Trigger declaration is invalid\", cause)),\n    Effect.flatMap(Schedule.validate)\n  )\n"]}

package/dist/esm/TriggerError.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Stable trigger failures.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Stable trigger failure codes.
+ *
+ * Each code names one refusal a caller can branch on. `store` covers only a
+ * persistence failure the store itself raised; a Control or runner failure is
+ * `runner`, a malformed scheduler option is `invalid_options`, and a claim
+ * refused by the durable declaration is `unknown_trigger`, `trigger_disabled`,
+ * or `revision_mismatch`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const TriggerErrorCode: Schema.Literals<readonly ["unknown_trigger", "trigger_disabled", "revision_mismatch", "stale_owner", "invalid_schedule", "invalid_trigger", "invalid_options", "invalid_cron", "unsatisfiable_cron", "verification_failed", "catch_up_bound_exceeded", "runner", "runner_timeout", "store"]>;
+/**
+ * Stable trigger failure code.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type TriggerErrorCode = typeof TriggerErrorCode.Type;
+declare const TriggerError_base: Schema.Class<TriggerError, Schema.TaggedStruct<"flows/triggers/TriggerError", {
+    readonly code: Schema.Literals<readonly ["unknown_trigger", "trigger_disabled", "revision_mismatch", "stale_owner", "invalid_schedule", "invalid_trigger", "invalid_options", "invalid_cron", "unsatisfiable_cron", "verification_failed", "catch_up_bound_exceeded", "runner", "runner_timeout", "store"]>;
+    readonly message: Schema.String;
+    readonly path: Schema.optional<Schema.String>;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A typed schedule, verification, or persistence failure.
+ *
+ * `path` is the dotted field path a declaration failure belongs to, so a
+ * caller reads the offending field structurally instead of parsing `message`.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class TriggerError extends TriggerError_base {
+}
+/**
+ * Builds a declaration failure that names the offending field.
+ *
+ * The whole `SchemaError` is deliberately not kept as the cause: serializing
+ * one costs about five kilobytes of schema AST per failure, and every byte of
+ * it past the rendered issue tree repeats what the tree already says.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fromSchemaError: (code: TriggerErrorCode, summary: string, error: unknown) => TriggerError;
+export {};
+//# sourceMappingURL=TriggerError.d.ts.map

package/dist/esm/TriggerError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TriggerError.d.ts","sourceRoot":"","sources":["../../src/TriggerError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,8RAe3B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;;;;;;;AAE3D;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,iBAKhC;CAAG;AA2CL;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,gBAAgB,EACtB,SAAS,MAAM,EACf,OAAO,OAAO,KACb,YAUF,CAAA"}

package/dist/esm/TriggerError.js

@@ -0,0 +1,110 @@
+/**
+ * Stable trigger failures.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Stable trigger failure codes.
+ *
+ * Each code names one refusal a caller can branch on. `store` covers only a
+ * persistence failure the store itself raised; a Control or runner failure is
+ * `runner`, a malformed scheduler option is `invalid_options`, and a claim
+ * refused by the durable declaration is `unknown_trigger`, `trigger_disabled`,
+ * or `revision_mismatch`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const TriggerErrorCode = Schema.Literals([
+    "unknown_trigger",
+    "trigger_disabled",
+    "revision_mismatch",
+    "stale_owner",
+    "invalid_schedule",
+    "invalid_trigger",
+    "invalid_options",
+    "invalid_cron",
+    "unsatisfiable_cron",
+    "verification_failed",
+    "catch_up_bound_exceeded",
+    "runner",
+    "runner_timeout",
+    "store"
+]);
+/**
+ * A typed schedule, verification, or persistence failure.
+ *
+ * `path` is the dotted field path a declaration failure belongs to, so a
+ * caller reads the offending field structurally instead of parsing `message`.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class TriggerError extends Schema.TaggedError()("flows/triggers/TriggerError", {
+    code: TriggerErrorCode,
+    message: Schema.String,
+    path: Schema.optional(Schema.String),
+    cause: Schema.optional(Schema.Defect())
+}) {
+}
+/**
+ * Walks a schema issue tree for the path of the first offending value.
+ *
+ * The tree is read defensively: only `path`, `issue`, and `issues` are
+ * consulted, so an issue shape this function does not recognize degrades to
+ * "no path" rather than throwing inside an error constructor.
+ */
+const issuePath = (issue) => {
+    if (typeof issue !== "object" || issue === null)
+        return undefined;
+    const node = issue;
+    const segments = Array.isArray(node.path) ? node.path.map((segment) => String(segment)) : [];
+    const children = Array.isArray(node.issues)
+        ? node.issues
+        : node.issue === undefined
+            ? []
+            : [node.issue];
+    for (const child of children) {
+        const nested = issuePath(child);
+        if (nested !== undefined)
+            return [...segments, ...nested];
+    }
+    return segments.length === 0 ? undefined : segments;
+};
+/**
+ * Renders a schema decode failure as one line, without the offending value.
+ *
+ * The rendered issue tree names the expectation and the path only, which is
+ * what makes it safe to keep in `message` and in `cause`: a secret submitted
+ * in the declaration never reaches either.
+ */
+const summarize = (error) => String(error)
+    .replace(/^SchemaError\(/, "")
+    .replace(/\)$/, "")
+    .replace(/\s*\n\s*/g, " ")
+    .trim();
+/**
+ * Builds a declaration failure that names the offending field.
+ *
+ * The whole `SchemaError` is deliberately not kept as the cause: serializing
+ * one costs about five kilobytes of schema AST per failure, and every byte of
+ * it past the rendered issue tree repeats what the tree already says.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fromSchemaError = (code, summary, error) => {
+    const path = issuePath(error?.issue);
+    const detail = summarize(error);
+    const field = path === undefined ? undefined : path.join(".");
+    return new TriggerError({
+        code,
+        message: field === undefined ? `${summary}: ${detail}` : `${summary} at ${field}: ${detail}`,
+        ...(field === undefined ? {} : { path: field }),
+        cause: detail
+    });
+};
+//# sourceMappingURL=TriggerError.js.map

package/dist/esm/TriggerError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TriggerError.js","sourceRoot":"","sources":["../../src/TriggerError.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Stable trigger failures.\n *\n * @see packages/smithers/agent/triggers/docs/api.md\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Stable trigger failure codes.\n *\n * Each code names one refusal a caller can branch on. `store` covers only a\n * persistence failure the store itself raised; a Control or runner failure is\n * `runner`, a malformed scheduler option is `invalid_options`, and a claim\n * refused by the durable declaration is `unknown_trigger`, `trigger_disabled`,\n * or `revision_mismatch`.\n *\n * @category models\n * @since 0.1.0\n */\nexport const TriggerErrorCode = Schema.Literals([\n  \"unknown_trigger\",\n  \"trigger_disabled\",\n  \"revision_mismatch\",\n  \"stale_owner\",\n  \"invalid_schedule\",\n  \"invalid_trigger\",\n  \"invalid_options\",\n  \"invalid_cron\",\n  \"unsatisfiable_cron\",\n  \"verification_failed\",\n  \"catch_up_bound_exceeded\",\n  \"runner\",\n  \"runner_timeout\",\n  \"store\"\n])\n\n/**\n * Stable trigger failure code.\n *\n * @category models\n * @since 0.1.0\n */\nexport type TriggerErrorCode = typeof TriggerErrorCode.Type\n\n/**\n * A typed schedule, verification, or persistence failure.\n *\n * `path` is the dotted field path a declaration failure belongs to, so a\n * caller reads the offending field structurally instead of parsing `message`.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class TriggerError extends Schema.TaggedError<TriggerError>()(\"flows/triggers/TriggerError\", {\n  code: TriggerErrorCode,\n  message: Schema.String,\n  path: Schema.optional(Schema.String),\n  cause: Schema.optional(Schema.Defect())\n}) {}\n\n/**\n * Walks a schema issue tree for the path of the first offending value.\n *\n * The tree is read defensively: only `path`, `issue`, and `issues` are\n * consulted, so an issue shape this function does not recognize degrades to\n * \"no path\" rather than throwing inside an error constructor.\n */\nconst issuePath = (issue: unknown): ReadonlyArray<string> | undefined => {\n  if (typeof issue !== \"object\" || issue === null) return undefined\n  const node = issue as {\n    readonly path?: unknown\n    readonly issue?: unknown\n    readonly issues?: unknown\n  }\n  const segments = Array.isArray(node.path) ? node.path.map((segment) => String(segment)) : []\n  const children = Array.isArray(node.issues)\n    ? node.issues\n    : node.issue === undefined\n    ? []\n    : [node.issue]\n  for (const child of children) {\n    const nested = issuePath(child)\n    if (nested !== undefined) return [...segments, ...nested]\n  }\n  return segments.length === 0 ? undefined : segments\n}\n\n/**\n * Renders a schema decode failure as one line, without the offending value.\n *\n * The rendered issue tree names the expectation and the path only, which is\n * what makes it safe to keep in `message` and in `cause`: a secret submitted\n * in the declaration never reaches either.\n */\nconst summarize = (error: unknown): string =>\n  String(error)\n    .replace(/^SchemaError\\(/, \"\")\n    .replace(/\\)$/, \"\")\n    .replace(/\\s*\\n\\s*/g, \" \")\n    .trim()\n\n/**\n * Builds a declaration failure that names the offending field.\n *\n * The whole `SchemaError` is deliberately not kept as the cause: serializing\n * one costs about five kilobytes of schema AST per failure, and every byte of\n * it past the rendered issue tree repeats what the tree already says.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const fromSchemaError = (\n  code: TriggerErrorCode,\n  summary: string,\n  error: unknown\n): TriggerError => {\n  const path = issuePath((error as { readonly issue?: unknown } | null)?.issue)\n  const detail = summarize(error)\n  const field = path === undefined ? undefined : path.join(\".\")\n  return new TriggerError({\n    code,\n    message: field === undefined ? `${summary}: ${detail}` : `${summary} at ${field}: ${detail}`,\n    ...(field === undefined ? {} : { path: field }),\n    cause: detail\n  })\n}\n"]}