things-api 0.10.0 → 0.12.0

package/dist/write/recurrence-rule-blob.js

@@ -0,0 +1,150 @@
+/**
+ * The recurrence-rule SERIALIZER — the write-side inverse of the read-only
+ * decoder in {@link ../model/recurrence.ts}. It composes the `rt1_recurrenceRule`
+ * XML plist the Things app writes for a repeating template, in the exact shape
+ * the decoder round-trips (rrv=4, the `of` offset grammar, the year-4001 "forever"
+ * `ed` sentinel).
+ *
+ * Two consumers share it, and NEITHER writes to a real Things database:
+ *  - the SIMULATOR write vector (src/write/vectors/simulator.ts), which applies
+ *    the RSIM-characterized recurrence mutations as SQL against a synthetic
+ *    fixture DB (docs/lab/rsim-results.md); and
+ *  - the bench WORLD profile (bench/world.ts), which seeds synthetic templates.
+ *
+ * Repeat rules remain UI-only on any real surface (writes go through the app's
+ * Repeat dialog, never SQLite) — this serializer exists solely so bench/simulated
+ * writes can reproduce the app's row shape without a Things install. The
+ * low-level {@link ruleXml} takes a numeric {@link RuleSpec}; {@link composeRepeatRuleSpec}
+ * maps the consumer-facing {@link RepeatRuleParams} vocabulary onto that spec.
+ */
+import {} from "../model/dates.js";
+import { WEEKDAY_TO_WD } from "./repeat-rule.js";
+/** Distant-future `ed` sentinel (year 4001 — the same class the app writes). */
+export const RULE_FOREVER = 64_092_211_200;
+/** Recurrence-unit code for each frequency (mirrors the decoder's UNITS map). */
+export const FREQUENCY_TO_FU = {
+    daily: 16,
+    weekly: 256,
+    monthly: 8,
+    yearly: 4,
+};
+/** Compose an `rt1_recurrenceRule` XML plist the read-path decoder accepts. */
+export function ruleXml(spec) {
+    const offsets = (spec.of ?? [{ dy: 0 }])
+        .map((o) => {
+        const entries = Object.entries(o)
+            .map(([k, v]) => `<key>${k}</key><integer>${v}</integer>`)
+            .join("");
+        return `<dict>${entries}</dict>`;
+    })
+        .join("");
+    return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
+        `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n` +
+        `<plist version="1.0"><dict>` +
+        `<key>ed</key><integer>${spec.ed ?? RULE_FOREVER}</integer>` +
+        `<key>fa</key><integer>${spec.fa}</integer>` +
+        `<key>fu</key><integer>${spec.fu}</integer>` +
+        `<key>ia</key><integer>${spec.anchor}</integer>` +
+        `<key>of</key><array>${offsets}</array>` +
+        `<key>rc</key><integer>${spec.rc ?? 0}</integer>` +
+        `<key>rrv</key><integer>4</integer>` +
+        `<key>sr</key><integer>${spec.anchor}</integer>` +
+        `<key>tp</key><integer>${spec.tp}</integer>` +
+        `<key>ts</key><integer>${spec.ts ?? 0}</integer>` +
+        `</dict></plist>\n`);
+}
+// -------------------------------------------------- vocabulary → spec
+const ymd = (iso) => iso.split("-").map(Number);
+/** Weekday (0 = Sunday) of an ISO date, evaluated at UTC noon (tz-invariant). */
+function weekdayOf(iso) {
+    const [y, m, d] = ymd(iso);
+    return new Date(Date.UTC(y, m - 1, d, 12)).getUTCDay();
+}
+/**
+ * The `of` offsets for a rule. A FIXED rule anchors on its calendar placement —
+ * the explicit weekdays/monthly/yearly anchor when given, else derived from the
+ * occurrence date (`refIso`): a weekly rule fires on the occurrence's weekday, a
+ * monthly one on its day-of-month, a yearly one on its month + day. An
+ * AFTER-COMPLETION rule has NO calendar day, so Things writes only the unit's
+ * nominal zero-index offset (UIC6-e: weekly of=[{wd:0}], monthly of=[{dy:0}]);
+ * the decoder ignores it. Only the weekly after-completion shape is RSIM-proven
+ * (RSIM2); the daily/monthly/yearly nominals follow the UIC6-e convention.
+ */
+function composeOffsets(params, refIso) {
+    if (params.afterCompletion === true) {
+        switch (params.frequency) {
+            case "daily":
+                return [{ dy: 0 }];
+            case "weekly":
+                return [{ wd: 0 }];
+            case "monthly":
+                return [{ dy: 0 }];
+            case "yearly":
+                return [{ mo: 0, dy: 0 }];
+        }
+    }
+    switch (params.frequency) {
+        case "daily":
+            return [{ dy: 0 }];
+        case "weekly": {
+            if (params.weekdays !== undefined) {
+                return params.weekdays.map((w) => ({ wd: WEEKDAY_TO_WD[w] }));
+            }
+            return [{ wd: weekdayOf(refIso) }];
+        }
+        case "monthly": {
+            const anchor = params.monthly;
+            if (anchor === undefined)
+                return [{ dy: ymd(refIso)[2] - 1 }];
+            return [monthlyOffset(anchor)];
+        }
+        case "yearly": {
+            const anchor = params.yearly;
+            if (anchor === undefined) {
+                const [, m, d] = ymd(refIso);
+                return [{ mo: m - 1, dy: d - 1 }];
+            }
+            return [{ mo: anchor.month - 1, ...monthlyOffset(anchor) }];
+        }
+    }
+}
+/** One month/year day anchor → its offset entry (day-of-month OR nth-weekday). */
+function monthlyOffset(anchor) {
+    if ("day" in anchor) {
+        return { dy: anchor.day === "last" ? -1 : anchor.day - 1 };
+    }
+    return {
+        wd: WEEKDAY_TO_WD[anchor.weekday],
+        wdo: anchor.ordinal === "last" ? -1 : anchor.ordinal,
+    };
+}
+/**
+ * Map the extended {@link RepeatRuleParams} vocabulary onto a numeric
+ * {@link RuleSpec}. `refIso` is the occurrence date the calendar anchor derives
+ * from when no explicit anchor is given; `anchor` seeds the (decoder-ignored)
+ * sr/ia epochs. A deadlined rule carries the start-offset in `ts` (ts = −N days
+ * earlier); the template's own `deadline` sentinel column — set by the applier,
+ * not here — is what actually flags deadline-ness (oddities §8a).
+ */
+export function composeRepeatRuleSpec(params, refIso, anchor) {
+    const deadlined = params.deadline === true || (params.startDaysEarlier ?? 0) > 0;
+    const spec = {
+        tp: params.afterCompletion === true ? 1 : 0,
+        fu: FREQUENCY_TO_FU[params.frequency],
+        fa: params.interval,
+        ts: deadlined ? -(params.startDaysEarlier ?? 0) : 0,
+        of: composeOffsets(params, refIso),
+        anchor,
+    };
+    const ends = params.ends;
+    if (ends !== undefined && ends.kind !== "never") {
+        if (ends.kind === "on-date") {
+            spec.ed = Math.floor(Date.parse(`${ends.date}T00:00:00Z`) / 1000);
+        }
+        else {
+            spec.rc = ends.count;
+        }
+    }
+    return spec;
+}
+//# sourceMappingURL=recurrence-rule-blob.js.map

package/dist/write/recurrence-rule-blob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence-rule-blob.js","sourceRoot":"","sources":["../../src/write/recurrence-rule-blob.ts"],"names":[],"mappings":"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"}

package/dist/write/reorder.d.ts

@@ -1,10 +1,30 @@
 import type { ReorderParams } from "./operations.ts";
 import { type MutationResult, type WriteDeps, type WriteOptions } from "./pipeline.ts";
 /**
- * Bounce cost is 2 verified mutations per item; beyond this the today scope
- * should use the native strategy and the evening scope should be re-thought.
+ * DEFAULT bounce cap — 2 verified mutations per item (~110 ms/item guest-local,
+ * BOUNCE2-t). The effective cap is `config.bounceMaxItems` (default 30); this
+ * constant is the built-in fallback used when a caller supplies no config value,
+ * and the figure surface copy cites.
  */
-export declare const BOUNCE_MAX_ITEMS = 10;
+export declare const BOUNCE_MAX_ITEMS = 30;
+/**
+ * The bounce re-entry law (reordgaps-results.md, BOUNCE2). A `when=` round-trip
+ * re-inserts the touched item; the DIRECTION depends on its containment context,
+ * and the away/back legs depend on its resting bucket:
+ *   - loose/area-direct items FRONT-insert (reverse-order legs land target order)
+ *   - strict-container children (heading/project) BACK-insert (forward-order legs)
+ * `away`/`back` are the two `when=` values of the round-trip; the resting bucket
+ * is `back`.
+ */
+export type BounceKind = "today" | "evening" | "day" | "projects" | "heading" | "area-someday" | "anytime" | "project-someday" | "someday";
+/**
+ * The bounce kinds whose N-item round-trip is eligible for the `things:///json`
+ * one-array collapse (BOUNCEJSON §9i) — exactly the classes whose placement
+ * (`back`) leg is `when=anytime` into a loose/heading-container bucket. Exported
+ * for the classification regression test (guards against "optimizing" a someday-
+ * placement or area-direct class into json, which §9i proves is a silent no-op).
+ */
+export declare function bounceJsonCollapsible(kind: BounceKind): boolean;
 export type ReorderResult = MutationResult | {
     kind: "bounce-aborted";
     op: "reorder";