@classytic/primitives 0.21.0 → 0.22.0

package/dist/environment.d.mts

@@ -76,9 +76,14 @@ declare function classifyEnv(env: string | undefined | null): EnvClass;
 /**
  * `true` when the value classifies as production.
  *
- * A named predicate rather than a `classifyEnv(x) === 'production'` at each call site: the raw
- * comparison is the shape that caused every defect listed above, so the codebase should not contain
- * one — even a correct one — for a reader to copy.
+ * A named predicate rather than a `classifyEnv(x) === 'production'` at each call site: a literal
+ * comparison against an env string is the exact shape that caused every defect listed above, so
+ * this module should not contain one — even a correct one — for the next reader to copy.
+ *
+ * Deliberately the ONLY predicate. `isTest` / `isDevelopment` were added and removed the same day:
+ * they had zero importers, because consumers that need all three buckets build their own triple
+ * from `classifyEnv` (be-prod's `config.*`, gym's `businessMode()`). Speculative surface on a
+ * published package is not free — it has to be supported, and it invited a needless version bump.
  */
 declare function isProductionEnv(env: string | undefined | null): boolean;
 //#endregion

package/dist/environment.mjs

@@ -37,9 +37,14 @@ function classifyEnv(env) {
 /**
 * `true` when the value classifies as production.
 *
-* A named predicate rather than a `classifyEnv(x) === 'production'` at each call site: the raw
-* comparison is the shape that caused every defect listed above, so the codebase should not contain
-* one — even a correct one — for a reader to copy.
+* A named predicate rather than a `classifyEnv(x) === 'production'` at each call site: a literal
+* comparison against an env string is the exact shape that caused every defect listed above, so
+* this module should not contain one — even a correct one — for the next reader to copy.
+*
+* Deliberately the ONLY predicate. `isTest` / `isDevelopment` were added and removed the same day:
+* they had zero importers, because consumers that need all three buckets build their own triple
+* from `classifyEnv` (be-prod's `config.*`, gym's `businessMode()`). Speculative surface on a
+* published package is not free — it has to be supported, and it invited a needless version bump.
 */
 function isProductionEnv(env) {
 	return classifyEnv(env) === "production";

package/dist/memory-outbox.d.mts

@@ -3,7 +3,7 @@ import { OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFa
 //#region src/events/memory-outbox.d.ts
 interface MemoryEntry {
   event: DomainEvent;
-  status: "pending" | "delivered" | "dead_letter";
+  status: 'pending' | 'delivered' | 'dead_letter';
   attempts: number;
   visibleAt: number;
   leaseOwner: string | null;

package/dist/memory-outbox.mjs

@@ -1,13 +1,5 @@
 import { InvalidOutboxEventError, OutboxOwnershipError } from "./outbox.mjs";
 //#region src/events/memory-outbox.ts
-/**
-* In-memory outbox store — reference implementation for dev / testing.
-*
-* Supports the full `OutboxStore` capability set (claim/lease, fail/retry,
-* dedupe, visibleAt). Production deployments should pass a `repository` to
-* `EventOutbox` instead of using this; the memory store exists for unit
-* tests and single-process dev where durable persistence is noise.
-*/
 const DEFAULT_LEASE_MS = 3e4;
 var MemoryOutboxStore = class {
 	entries = [];

package/dist/period.d.mts

@@ -160,6 +160,30 @@ declare function resolvePeriod(period: Period, timezone?: string): DateRange;
  * For the `$lte` call sites that predate half-open ranges. Derived from the
  * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
  */
+/**
+ * Shift a MONTH or QUARTER period by `n` of its own units (negative = back).
+ *
+ * The arithmetic a caller would otherwise write inline, and the reason this is
+ * here rather than in each of them: "two filing months ago" is a `Period`
+ * question, and the shapes reachable without it are both wrong in the same way.
+ *
+ *   `new Date(Date.UTC(y, m - 1 - n, 1))` — a UTC instant used to answer a
+ *   BUSINESS-calendar question. Six hours off in Asia/Dhaka at both ends; the
+ *   five silent defects in this module's header are all that shape.
+ *
+ *   hand-rolled integer math (`y * 12 + (m - 1) - n`) — correct, but it is a
+ *   third copy of a rule the `Period` type already owns, and the year rollover
+ *   is exactly where a copy goes wrong.
+ *
+ * NO Date is constructed and no zone is consulted: shifting a month is pure
+ * calendar arithmetic on `(year, month)`. The `timezone` rides along unchanged,
+ * so the shifted period still resolves against the calendar it was defined in —
+ * `resolvePeriod` / {@link resolveMonth} remain the only places instants appear.
+ *
+ * A YEAR period shifts by years; a `custom` (ad-hoc start/end) period has no
+ * unit to shift and throws rather than guessing one.
+ */
+declare function shiftPeriod(period: Period, n: number): Period;
 declare function inclusiveEnd(range: DateRange): Date;
 /**
  * The period an INSTANT falls in, on the local calendar.
@@ -185,4 +209,4 @@ declare function parsePeriod(label: string, timezone?: string): Period;
  */
 declare function formatPeriod(period: Period): string;
 //#endregion
-export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear };
+export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/period.mjs

@@ -261,6 +261,55 @@ function resolvePeriod(period, timezone) {
 * For the `$lte` call sites that predate half-open ranges. Derived from the
 * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
 */
+/**
+* Shift a MONTH or QUARTER period by `n` of its own units (negative = back).
+*
+* The arithmetic a caller would otherwise write inline, and the reason this is
+* here rather than in each of them: "two filing months ago" is a `Period`
+* question, and the shapes reachable without it are both wrong in the same way.
+*
+*   `new Date(Date.UTC(y, m - 1 - n, 1))` — a UTC instant used to answer a
+*   BUSINESS-calendar question. Six hours off in Asia/Dhaka at both ends; the
+*   five silent defects in this module's header are all that shape.
+*
+*   hand-rolled integer math (`y * 12 + (m - 1) - n`) — correct, but it is a
+*   third copy of a rule the `Period` type already owns, and the year rollover
+*   is exactly where a copy goes wrong.
+*
+* NO Date is constructed and no zone is consulted: shifting a month is pure
+* calendar arithmetic on `(year, month)`. The `timezone` rides along unchanged,
+* so the shifted period still resolves against the calendar it was defined in —
+* `resolvePeriod` / {@link resolveMonth} remain the only places instants appear.
+*
+* A YEAR period shifts by years; a `custom` (ad-hoc start/end) period has no
+* unit to shift and throws rather than guessing one.
+*/
+function shiftPeriod(period, n) {
+	if (!Number.isInteger(n)) throw new PeriodError("INVALID_FIELD", `shiftPeriod expects an integer offset, received ${String(n)}.`);
+	const granularity = granularityOf(period);
+	const zone = period.timezone !== void 0 ? { timezone: period.timezone } : {};
+	if (granularity === "month") {
+		const zeroBased = period.year * 12 + (period.month - 1) + n;
+		return {
+			year: Math.floor(zeroBased / 12),
+			month: zeroBased % 12 + 1,
+			...zone
+		};
+	}
+	if (granularity === "quarter") {
+		const zeroBased = period.year * 4 + (period.quarter - 1) + n;
+		return {
+			year: Math.floor(zeroBased / 4),
+			quarter: zeroBased % 4 + 1,
+			...zone
+		};
+	}
+	if (granularity === "year") return {
+		year: period.year + n,
+		...zone
+	};
+	throw new PeriodError("AMBIGUOUS_PERIOD", "shiftPeriod has no unit to shift for an ad-hoc start/end period — shift the instants, or use a calendar period.");
+}
 function inclusiveEnd(range) {
 	assertUsableRange(range, "range");
 	return /* @__PURE__ */ new Date(range.end.getTime() - 1);
@@ -339,4 +388,4 @@ function formatPeriod(period) {
 	throw new PeriodError("INVALID_LABEL", "An ad-hoc Period (start + end) has no canonical label.");
 }
 //#endregion
-export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear };
+export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",