@hogsend/core 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "drizzle-orm": "^0.45.2",
     "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.2.0"
+    "@hogsend/db": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/conditions/builder.ts

@@ -0,0 +1,163 @@
+import type { DurationObject } from "../duration.js";
+import type {
+  CompositeCondition,
+  ConditionEval,
+  EventCondition,
+  PropertyCondition,
+} from "../types/conditions.js";
+
+type CountOperator = NonNullable<EventCondition["operator"]>;
+
+/** Fluent property predicate. Each terminal returns a plain PropertyCondition. */
+export interface PropertyMatcher {
+  eq(value: string | number | boolean): PropertyCondition;
+  neq(value: string | number | boolean): PropertyCondition;
+  gt(value: number): PropertyCondition;
+  gte(value: number): PropertyCondition;
+  lt(value: number): PropertyCondition;
+  lte(value: number): PropertyCondition;
+  contains(value: string | number | boolean): PropertyCondition;
+  exists(): PropertyCondition;
+  notExists(): PropertyCondition;
+}
+
+/**
+ * Fluent event predicate. The optional `.within(window)` precedes the terminal
+ * (`b.event("x").within(days(7)).notExists()`) so every terminal still returns a
+ * clean EventCondition POJO — no wrapper objects to unwrap.
+ */
+export interface EventMatcher {
+  /** Constrain to a rolling window — this is what makes a bucket time-based. */
+  within(window: DurationObject): EventMatcher;
+  exists(): EventCondition;
+  notExists(): EventCondition;
+  count(operator: CountOperator, value: number): EventCondition;
+  atLeast(value: number): EventCondition;
+  moreThan(value: number): EventCondition;
+  atMost(value: number): EventCondition;
+  lessThan(value: number): EventCondition;
+  exactly(value: number): EventCondition;
+}
+
+/**
+ * The fluent builder passed to a `defineBucket` criteria function. Every terminal
+ * returns a plain `ConditionEval` POJO — byte-identical to the declarative form —
+ * so the registry indexes, schema validation, reconcile cron, and Studio all keep
+ * working unchanged. The function runs ONCE, at bucket-definition time; it never
+ * executes per-user, so criteria stays introspectable data.
+ */
+export interface CriteriaBuilder {
+  prop(property: string): PropertyMatcher;
+  event(eventName: string): EventMatcher;
+  /** Composite AND over the given conditions. */
+  all(...conditions: ConditionEval[]): CompositeCondition;
+  /** Composite OR over the given conditions. */
+  any(...conditions: ConditionEval[]): CompositeCondition;
+}
+
+class PropertyMatcherImpl implements PropertyMatcher {
+  private readonly property: string;
+  constructor(property: string) {
+    this.property = property;
+  }
+  private make(
+    operator: PropertyCondition["operator"],
+    value?: string | number | boolean,
+  ): PropertyCondition {
+    return {
+      type: "property",
+      property: this.property,
+      operator,
+      ...(value !== undefined ? { value } : {}),
+    };
+  }
+  eq(value: string | number | boolean): PropertyCondition {
+    return this.make("eq", value);
+  }
+  neq(value: string | number | boolean): PropertyCondition {
+    return this.make("neq", value);
+  }
+  gt(value: number): PropertyCondition {
+    return this.make("gt", value);
+  }
+  gte(value: number): PropertyCondition {
+    return this.make("gte", value);
+  }
+  lt(value: number): PropertyCondition {
+    return this.make("lt", value);
+  }
+  lte(value: number): PropertyCondition {
+    return this.make("lte", value);
+  }
+  contains(value: string | number | boolean): PropertyCondition {
+    return this.make("contains", value);
+  }
+  exists(): PropertyCondition {
+    return this.make("exists");
+  }
+  notExists(): PropertyCondition {
+    return this.make("not_exists");
+  }
+}
+
+class EventMatcherImpl implements EventMatcher {
+  private readonly eventName: string;
+  private readonly window?: DurationObject;
+  constructor(eventName: string, window?: DurationObject) {
+    this.eventName = eventName;
+    this.window = window;
+  }
+  within(window: DurationObject): EventMatcher {
+    return new EventMatcherImpl(this.eventName, window);
+  }
+  private make(
+    check: EventCondition["check"],
+    operator?: CountOperator,
+    value?: number,
+  ): EventCondition {
+    return {
+      type: "event",
+      eventName: this.eventName,
+      check,
+      ...(operator !== undefined ? { operator } : {}),
+      ...(value !== undefined ? { value } : {}),
+      ...(this.window !== undefined ? { within: this.window } : {}),
+    };
+  }
+  exists(): EventCondition {
+    return this.make("exists");
+  }
+  notExists(): EventCondition {
+    return this.make("not_exists");
+  }
+  count(operator: CountOperator, value: number): EventCondition {
+    return this.make("count", operator, value);
+  }
+  atLeast(value: number): EventCondition {
+    return this.make("count", "gte", value);
+  }
+  moreThan(value: number): EventCondition {
+    return this.make("count", "gt", value);
+  }
+  atMost(value: number): EventCondition {
+    return this.make("count", "lte", value);
+  }
+  lessThan(value: number): EventCondition {
+    return this.make("count", "lt", value);
+  }
+  exactly(value: number): EventCondition {
+    return this.make("count", "eq", value);
+  }
+}
+
+/**
+ * The default {@link CriteriaBuilder} instance. `defineBucket` passes this to a
+ * criteria function and stores the returned `ConditionEval`. Exported so it can
+ * also be used standalone (e.g. composing reusable criteria fragments in tests).
+ */
+export const criteriaBuilder: CriteriaBuilder = {
+  prop: (property) => new PropertyMatcherImpl(property),
+  event: (eventName) => new EventMatcherImpl(eventName),
+  all: (...conditions) => ({ type: "composite", operator: "and", conditions }),
+  any: (...conditions) => ({ type: "composite", operator: "or", conditions }),
+};

package/src/conditions/index.ts

@@ -1,3 +1,9 @@
+export {
+  type CriteriaBuilder,
+  criteriaBuilder,
+  type EventMatcher,
+  type PropertyMatcher,
+} from "./builder.js";
 export { type ConditionContext, evaluateCondition } from "./evaluate.js";
 export { evaluateEventCondition } from "./event.js";
 export { evaluatePropertyConditions } from "./property.js";

package/src/index.ts

@@ -1,8 +1,12 @@
 export {
   type ConditionContext,
+  type CriteriaBuilder,
+  criteriaBuilder,
+  type EventMatcher,
   evaluateCondition,
   evaluateEventCondition,
   evaluatePropertyConditions,
+  type PropertyMatcher,
 } from "./conditions/index.js";
 export {
   type DurationObject,

package/src/schemas/bucket.schema.ts

@@ -72,8 +72,8 @@ export const bucketMetaSchema = z
 
     criteria: conditionEvalSchema.optional(),
 
-    reentry: z.enum(["once", "once_per_period", "unlimited"]).optional(),
-    reentryPeriod: durationObjectSchema.optional(),
+    entryLimit: z.enum(["once", "once_per_period", "unlimited"]).optional(),
+    entryPeriod: durationObjectSchema.optional(),
 
     minDwell: durationObjectSchema.optional(),
     maxDwell: durationObjectSchema.optional(),
@@ -105,15 +105,21 @@ export const bucketMetaSchema = z
       });
     }
 
-    // Rule 4: kind/criteria coherence. Manual buckets skip rules 1–3.
+    // Rule 4: kind/criteria coherence. `kind:"manual"` is declared on the
+    // discriminator for forward-compat (Phase 4) but is NOT implemented in v1 —
+    // it would register as a silent no-op (never populated by the real-time path
+    // or the reconcile cron). Reject it LOUDLY at registration time
+    // (bucketMetaSchema.parse) rather than accepting a bucket that can never
+    // gain members. This is a runtime-validation tightening, not a type break:
+    // the `kind` enum still allows declaring "manual".
     if (kind === "manual") {
-      if (criteria !== undefined) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["criteria"],
-          message: 'kind:"manual" buckets must not declare `criteria`.',
-        });
-      }
+      ctx.addIssue({
+        code: "custom",
+        path: ["kind"],
+        message:
+          'kind:"manual" buckets are not implemented in v1; use a dynamic ' +
+          'bucket (kind:"dynamic" with `criteria`) instead.',
+      });
       return;
     }
 

package/src/types/bucket.ts

@@ -15,6 +15,11 @@ export interface BucketMeta {
    * skipped by checkBucketMembership and the reconcile cron (early-continue, the
    * Laudspeaker pattern). Declaring it up front keeps Phase 4 genuinely additive
    * — no breaking change to BucketMeta later. Default "dynamic".
+   *
+   * v1: kind:"manual" is REJECTED at registration time (bucketMetaSchema parse)
+   * because nothing populates a manual bucket yet — it would be a silent no-op.
+   * The value stays on the enum for forward-compat; use kind:"dynamic" with
+   * `criteria` until full manual membership ships.
    */
   kind?: "dynamic" | "manual";
 
@@ -38,8 +43,8 @@ export interface BucketMeta {
    * re-emit only after a prior leave + period elapses; "unlimited" = always.
    * Default "unlimited".
    */
-  reentry?: "once" | "once_per_period" | "unlimited";
-  reentryPeriod?: DurationObject;
+  entryLimit?: "once" | "once_per_period" | "unlimited";
+  entryPeriod?: DurationObject;
 
   /**
    * Anti-flap: suppress bucket:left until membership has existed at least this
@@ -54,8 +59,8 @@ export interface BucketMeta {
    * `minDwell`, which is a floor). Use it for time-boxed membership: "in this
    * bucket for exactly N days, then out".
    *
-   * Re-entry after a maxDwell exit is governed by `reentry` (per-bucket): pair
-   * with `reentry:"once"` / `"once_per_period"` for a HARD time-box (they stay
+   * Re-entry after a maxDwell exit is governed by `entryLimit` (per-bucket): pair
+   * with `entryLimit:"once"` / `"once_per_period"` for a HARD time-box (they stay
    * out / cool off), or leave the default `"unlimited"` for a PERIODIC FLUSH
    * (they re-join on their next qualifying event). Independent of `within` and
    * `fastExpiry`; if `minDwell` is also set it must be <= `maxDwell` (validated).
@@ -71,8 +76,12 @@ export interface BucketMeta {
    *   a criteria walk if omitted; an explicit value overrides.
    * reconcileEvery: advisory cadence surfaced in Studio (the single engine-wide
    *   cron sweeps all time-based buckets; per-bucket cadence is informational).
-   * reconcileJoins: also re-evaluate JOINS in the sweep (default false — the
-   *   real-time path already catches joins on event arrival; keep the sweep
+   * reconcileJoins: also re-evaluate JOINS in the sweep. Tri-state:
+   *   `false` = hard OFF (cost-bounding override, even for absence buckets);
+   *   `true` = explicit ON; `undefined` = INFERRED — ON only for absence-shaped
+   *   criteria (a windowed `not_exists` leg, the sole shape a clock can JOIN, so
+   *   went-dormant works with no extra config), OFF otherwise (the real-time
+   *   path already catches positive joins on event arrival; keep the sweep
    *   O(active members)).
    * fastExpiry: opt-in per-user durable timer for sub-second absence-leave on
    *   latency-critical buckets (Approach A graft). The cron remains the

package/src/types/journey-context.ts

@@ -96,12 +96,47 @@ export interface EmailHistoryResult {
   count: number;
 }
 
+export interface WaitForEventOptions {
+  /** Event name to wait for (use your `Events` constant). Matched verbatim. */
+  event: string;
+  /**
+   * Max time to wait before resolving as timed-out. Required: an unbounded wait
+   * is only capped by the task's execution timeout and would fail rather than
+   * resume. Keep it within the journey execution timeout (720h / 30 days).
+   */
+  timeout: DurationObject;
+  /** Optional observability label written to `currentNodeId` while waiting. */
+  label?: string;
+}
+
+export interface WaitForEventResult {
+  /** `true` when the `timeout` elapsed first; `false` when the event fired. */
+  timedOut: boolean;
+}
+
 export interface JourneyContext {
   sleep(opts: SleepOptions): Promise<SleepResult>;
 
   /** Durable sleep until an absolute instant (`Date` or ISO string). */
   sleepUntil(at: Date | string, opts?: SleepUntilOptions): Promise<SleepResult>;
 
+  /**
+   * Durably wait until THIS user emits `event`, or `timeout` elapses —
+   * whichever comes first. The state is marked `"waiting"` while suspended and
+   * `"active"` again on resume. Returns `{ timedOut }` so the journey can branch
+   * (e.g. send a nudge on timeout, do nothing if the event arrived).
+   *
+   * Forward-looking: only events emitted AFTER the wait is established count —
+   * use `ctx.history.hasEvent` to check whether something already happened.
+   *
+   * If the journey exits (via `exitOn`) or is cancelled while waiting, the run
+   * is aborted cleanly (a `JourneyExitedError` is thrown and handled by the
+   * engine) so no post-wait side effects fire. After a long wait you should
+   * still re-check `ctx.guard.isSubscribed()` before sending, since an
+   * unsubscribe does not exit the journey.
+   */
+  waitForEvent(opts: WaitForEventOptions): Promise<WaitForEventResult>;
+
   /** Timezone-bound fluent scheduler. Always terminates in a `Date`. */
   when: WhenBuilder;