@baukit/notifications-core 0.7.2 → 0.7.4

package/src/plan-vectors.ts

@@ -0,0 +1,198 @@
+import type { FoldPolicy, GapPolicy, LocalTimeTransition } from '@baukit/localization-core';
+
+import { NotificationPlanError } from './errors.js';
+import {
+  resolveNotificationOccurrences,
+  type NotificationOccurrence,
+  type SkippedOccurrence,
+} from './occurrences.js';
+import { planNotificationReplacement } from './replacement-plan.js';
+import type { PlannedNotification } from './validation.js';
+
+export interface NotificationPlanVectorCurrent {
+  readonly logicalId: string;
+  readonly instant: string;
+  readonly contentDigest: string;
+}
+
+export interface NotificationPlanVectorInput {
+  readonly timeZone: string;
+  readonly gap: GapPolicy;
+  readonly fold: FoldPolicy;
+  readonly now: string;
+  readonly horizonDays: number;
+  readonly replaceAll?: boolean;
+  readonly occurrences: readonly NotificationOccurrence[];
+  readonly current: readonly NotificationPlanVectorCurrent[];
+}
+
+export interface NotificationPlanVectorResult {
+  readonly firstCivilDate: string;
+  readonly lastCivilDate: string;
+  readonly schedule: readonly {
+    readonly logicalId: string;
+    readonly instant: string;
+    readonly transition: LocalTimeTransition;
+  }[];
+  readonly keep: readonly string[];
+  readonly cancel: readonly string[];
+  readonly skipped: readonly SkippedOccurrence[];
+}
+
+export interface NotificationPlanVectorError {
+  readonly error: { readonly code: string; readonly logicalId?: string };
+}
+
+export interface NotificationPlanVectorCase {
+  readonly name: string;
+  readonly input: NotificationPlanVectorInput;
+  readonly expected: NotificationPlanVectorResult | NotificationPlanVectorError;
+}
+
+export interface NotificationPlanVectorFixture {
+  readonly version: number;
+  readonly cases: readonly NotificationPlanVectorCase[];
+}
+
+/** One vector: `actual()` must deep-equal `expected` (`undefined` fields count as absent). */
+export interface NotificationPlanVectorCheck {
+  readonly label: string;
+  readonly expected: unknown;
+  readonly actual: () => unknown;
+}
+
+interface Convergence {
+  readonly schedule: readonly unknown[];
+  readonly cancel: readonly unknown[];
+  readonly notKept: number;
+}
+
+/**
+ * Expands `fixtures/notifications/plan-vectors-v1.json` into checks. Each success case yields
+ * three: the expected plan, convergence once the plan is applied, and independence from input
+ * order. Each error case yields one check of the thrown `NotificationPlanError` code and ID.
+ */
+export function notificationPlanVectorChecks(
+  fixture: NotificationPlanVectorFixture,
+): NotificationPlanVectorCheck[] {
+  return fixture.cases.flatMap((entry) =>
+    isErrorCase(entry) ? [errorCheck(entry)] : successChecks(entry),
+  );
+}
+
+function isErrorCase(
+  entry: NotificationPlanVectorCase,
+): entry is NotificationPlanVectorCase & { expected: NotificationPlanVectorError } {
+  return 'error' in entry.expected;
+}
+
+function successChecks(entry: NotificationPlanVectorCase): NotificationPlanVectorCheck[] {
+  const { input } = entry;
+  return [
+    {
+      label: entry.name,
+      expected: entry.expected,
+      actual: () => summary(input, toCurrent(input.current)),
+    },
+    {
+      label: `${entry.name} converges after the plan is applied`,
+      expected: { schedule: [], cancel: [], notKept: 0 },
+      actual: () => convergence(input),
+    },
+    {
+      label: `${entry.name} does not depend on input order`,
+      expected: entry.expected,
+      actual: () =>
+        summary(
+          { ...input, occurrences: [...input.occurrences].reverse() },
+          toCurrent(input.current).reverse(),
+        ),
+    },
+  ];
+}
+
+function errorCheck(
+  entry: NotificationPlanVectorCase & { expected: NotificationPlanVectorError },
+): NotificationPlanVectorCheck {
+  const { code, logicalId } = entry.expected.error;
+  return {
+    label: entry.name,
+    expected: { error: { code, logicalId } },
+    actual: () => thrownPlanError(() => run(entry.input, toCurrent(entry.input.current))),
+  };
+}
+
+function toCurrent(entries: readonly NotificationPlanVectorCurrent[]): PlannedNotification[] {
+  return entries.map(({ logicalId, instant, contentDigest }) => ({
+    logicalId,
+    epochMilliseconds: Date.parse(instant),
+    contentDigest,
+  }));
+}
+
+function run(input: NotificationPlanVectorInput, current: readonly PlannedNotification[]) {
+  const resolution = resolveNotificationOccurrences({
+    occurrences: input.occurrences,
+    timeZone: input.timeZone,
+    gap: input.gap,
+    fold: input.fold,
+    clock: () => Date.parse(input.now),
+    horizonDays: input.horizonDays,
+  });
+  const plan = planNotificationReplacement(current, resolution.desired, {
+    replaceAll: input.replaceAll ?? false,
+  });
+  return { resolution, plan };
+}
+
+function summary(
+  input: NotificationPlanVectorInput,
+  current: readonly PlannedNotification[],
+): NotificationPlanVectorResult {
+  const { resolution, plan } = run(input, current);
+  return {
+    firstCivilDate: resolution.firstCivilDate,
+    lastCivilDate: resolution.lastCivilDate,
+    schedule: plan.schedule.map((entry) => ({
+      logicalId: entry.logicalId,
+      instant: new Date(entry.epochMilliseconds).toISOString().replace('.000Z', 'Z'),
+      transition: entry.transition,
+    })),
+    keep: plan.keep.map((entry) => entry.logicalId),
+    cancel: plan.cancel.map((entry) => entry.logicalId),
+    skipped: resolution.skipped,
+  };
+}
+
+function appliedPlan(input: NotificationPlanVectorInput): PlannedNotification[] {
+  const { plan } = run(input, toCurrent(input.current));
+  return [...plan.keep, ...plan.schedule].map(
+    ({ logicalId, epochMilliseconds, contentDigest }) => ({
+      logicalId,
+      epochMilliseconds,
+      contentDigest,
+    }),
+  );
+}
+
+function convergence(input: NotificationPlanVectorInput): Convergence {
+  const applied = appliedPlan(input);
+  const settled = summary({ ...input, replaceAll: false }, [...applied].reverse());
+  return {
+    schedule: settled.schedule,
+    cancel: settled.cancel,
+    notKept: applied.length - settled.keep.length,
+  };
+}
+
+function thrownPlanError(action: () => unknown): unknown {
+  try {
+    action();
+  } catch (error) {
+    if (error instanceof NotificationPlanError) {
+      return { error: { code: error.code, logicalId: error.logicalId } };
+    }
+    return { unexpected: String(error) };
+  }
+  return { unexpected: 'no error thrown' };
+}

package/src/replacement-plan.ts

@@ -0,0 +1,57 @@
+import {
+  assertPlannedNotifications,
+  compareByInstant,
+  type PlannedNotification,
+} from './validation.js';
+
+export interface NotificationReplacementOptions {
+  readonly replaceAll?: boolean;
+}
+
+export interface NotificationReplacementPlan<
+  TCurrent extends PlannedNotification,
+  TDesired extends PlannedNotification,
+> {
+  readonly keep: readonly TCurrent[];
+  readonly cancel: readonly TCurrent[];
+  readonly schedule: readonly TDesired[];
+}
+
+export function planNotificationReplacement<
+  TCurrent extends PlannedNotification,
+  TDesired extends PlannedNotification,
+>(
+  current: readonly TCurrent[],
+  desired: readonly TDesired[],
+  options: NotificationReplacementOptions = {},
+): NotificationReplacementPlan<TCurrent, TDesired> {
+  assertPlannedNotifications(current);
+  assertPlannedNotifications(desired);
+
+  const desiredById = new Map(desired.map((entry) => [entry.logicalId, entry]));
+  const keep: TCurrent[] = [];
+  const cancel: TCurrent[] = [];
+  const kept = new Set<string>();
+
+  for (const entry of current) {
+    const wanted = desiredById.get(entry.logicalId);
+    if (options.replaceAll !== true && wanted !== undefined && samePlacement(entry, wanted)) {
+      keep.push(entry);
+      kept.add(entry.logicalId);
+    } else {
+      cancel.push(entry);
+    }
+  }
+
+  return {
+    keep: keep.sort(compareByInstant),
+    cancel: cancel.sort(compareByInstant),
+    schedule: desired.filter((entry) => !kept.has(entry.logicalId)).sort(compareByInstant),
+  };
+}
+
+function samePlacement(left: PlannedNotification, right: PlannedNotification): boolean {
+  return (
+    left.epochMilliseconds === right.epochMilliseconds && left.contentDigest === right.contentDigest
+  );
+}

package/src/scheduler.ts

@@ -0,0 +1,287 @@
+import { NotificationPlanError } from './errors.js';
+import {
+  isOwnedBy,
+  ownedNotificationIdentifier,
+  type OwnedNotificationMarker,
+} from './ownership.js';
+import {
+  planNotificationReplacement,
+  type NotificationReplacementOptions,
+} from './replacement-plan.js';
+import {
+  assertNamespace,
+  assertPlannedNotifications,
+  type PlannedNotification,
+} from './validation.js';
+
+export type NotificationPermission = 'granted' | 'denied' | 'undetermined';
+
+export interface PendingNotification {
+  readonly identifier: string;
+  readonly marker: OwnedNotificationMarker | null;
+}
+
+export interface OwnedNotificationScheduleRequest<TContent> {
+  readonly identifier: string;
+  readonly marker: OwnedNotificationMarker;
+  readonly content: TContent;
+}
+
+export interface NotificationPlatform<TContent> {
+  list(): Promise<readonly PendingNotification[]>;
+  cancel(identifier: string): Promise<void>;
+  permission(): Promise<NotificationPermission>;
+  schedule(request: OwnedNotificationScheduleRequest<TContent>): Promise<void>;
+}
+
+export interface NotificationOwner {
+  readonly namespace: string;
+}
+
+export interface OwnedNotification<TContent> extends PlannedNotification {
+  readonly content: TContent;
+}
+
+export type OwnedNotificationFailureCode =
+  | 'list_failed'
+  | 'cancel_failed'
+  | 'permission_denied'
+  | 'permission_failed'
+  | 'schedule_failed'
+  | 'schedule_limit';
+
+export interface OwnedNotificationFailure {
+  readonly code: OwnedNotificationFailureCode;
+  readonly logicalId?: string;
+}
+
+export type OwnedNotificationReplacementStatus = 'complete' | 'incomplete' | 'superseded';
+
+export interface OwnedNotificationReplacementOutcome {
+  readonly status: OwnedNotificationReplacementStatus;
+  readonly kept: readonly string[];
+  readonly cancelled: readonly string[];
+  readonly scheduled: readonly string[];
+  readonly failures: readonly OwnedNotificationFailure[];
+}
+
+export interface OwnedNotificationScheduler<TContent> {
+  replaceOwned(
+    owner: NotificationOwner,
+    desired: readonly OwnedNotification<TContent>[],
+    options?: NotificationReplacementOptions,
+  ): Promise<OwnedNotificationReplacementOutcome>;
+}
+
+export interface OwnedNotificationSchedulerOptions {
+  readonly pendingLimit?: number;
+}
+
+type Replacement = () => Promise<OwnedNotificationReplacementOutcome>;
+
+interface QueuedReplacement {
+  readonly run: Replacement;
+  readonly resolve: (outcome: OwnedNotificationReplacementOutcome) => void;
+  readonly reject: (error: unknown) => void;
+}
+
+interface OwnerQueue {
+  waiting: QueuedReplacement | null;
+}
+
+interface ScheduleResult {
+  readonly scheduled: readonly string[];
+  readonly failures: readonly OwnedNotificationFailure[];
+}
+
+const SUPERSEDED: OwnedNotificationReplacementOutcome = Object.freeze({
+  status: 'superseded',
+  kept: [],
+  cancelled: [],
+  scheduled: [],
+  failures: [],
+});
+
+export function createOwnedNotificationScheduler<TContent>(
+  platform: NotificationPlatform<TContent>,
+  options: OwnedNotificationSchedulerOptions = {},
+): OwnedNotificationScheduler<TContent> {
+  const pendingLimit = options.pendingLimit ?? Number.POSITIVE_INFINITY;
+  if (pendingLimit !== Number.POSITIVE_INFINITY && !isPositiveInteger(pendingLimit)) {
+    throw new NotificationPlanError('invalid_pending_limit');
+  }
+  const queues = new Map<string, OwnerQueue>();
+
+  return {
+    async replaceOwned(owner, desired, replaceOptions = {}) {
+      assertNamespace(owner.namespace);
+      assertPlannedNotifications(desired);
+      const namespace = owner.namespace;
+      const snapshot = [...desired];
+      return enqueue(queues, namespace, () =>
+        replaceNow(platform, namespace, snapshot, replaceOptions, pendingLimit),
+      );
+    },
+  };
+}
+
+function enqueue(
+  queues: Map<string, OwnerQueue>,
+  namespace: string,
+  run: Replacement,
+): Promise<OwnedNotificationReplacementOutcome> {
+  return new Promise((resolve, reject) => {
+    const replacement = { run, resolve, reject };
+    const queue = queues.get(namespace);
+    if (queue === undefined) {
+      const created: OwnerQueue = { waiting: null };
+      queues.set(namespace, created);
+      start(queues, namespace, created, replacement);
+      return;
+    }
+    queue.waiting?.resolve(SUPERSEDED);
+    queue.waiting = replacement;
+  });
+}
+
+function start(
+  queues: Map<string, OwnerQueue>,
+  namespace: string,
+  queue: OwnerQueue,
+  replacement: QueuedReplacement,
+): void {
+  void replacement
+    .run()
+    .then(replacement.resolve, replacement.reject)
+    .finally(() => {
+      const next = queue.waiting;
+      queue.waiting = null;
+      if (next === null) {
+        queues.delete(namespace);
+        return;
+      }
+      start(queues, namespace, queue, next);
+    });
+}
+
+async function replaceNow<TContent>(
+  platform: NotificationPlatform<TContent>,
+  namespace: string,
+  desired: readonly OwnedNotification<TContent>[],
+  options: NotificationReplacementOptions,
+  pendingLimit: number,
+): Promise<OwnedNotificationReplacementOutcome> {
+  let pending: readonly PendingNotification[];
+  try {
+    pending = await platform.list();
+  } catch {
+    return outcome([], [], [], [{ code: 'list_failed' }]);
+  }
+
+  const current = pending.flatMap(({ identifier, marker }) =>
+    isOwnedBy(namespace, identifier, marker) ? [marker] : [],
+  );
+  const plan = planNotificationReplacement(current, desired, options);
+
+  const cancelFailures: OwnedNotificationFailure[] = [];
+  const cancelled: string[] = [];
+  for (const entry of plan.cancel) {
+    try {
+      await platform.cancel(ownedNotificationIdentifier(namespace, entry.logicalId));
+      cancelled.push(entry.logicalId);
+    } catch {
+      cancelFailures.push({ code: 'cancel_failed', logicalId: entry.logicalId });
+    }
+  }
+
+  const blocked = new Set(cancelFailures.map((failure) => failure.logicalId));
+  const toSchedule = plan.schedule.filter((entry) => !blocked.has(entry.logicalId));
+  const capacity = pendingLimit - (pending.length - cancelled.length);
+  const scheduling = await scheduleAll(platform, namespace, toSchedule, capacity);
+
+  return outcome(
+    plan.keep.map((entry) => entry.logicalId),
+    cancelled,
+    scheduling.scheduled,
+    [...cancelFailures, ...scheduling.failures],
+  );
+}
+
+async function scheduleAll<TContent>(
+  platform: NotificationPlatform<TContent>,
+  namespace: string,
+  entries: readonly OwnedNotification<TContent>[],
+  capacity: number,
+): Promise<ScheduleResult> {
+  if (entries.length === 0) {
+    return { scheduled: [], failures: [] };
+  }
+  const blockedCode = await permissionFailure(platform);
+  if (blockedCode !== null) {
+    return {
+      scheduled: [],
+      failures: entries.map((entry) => ({ code: blockedCode, logicalId: entry.logicalId })),
+    };
+  }
+
+  const scheduled: string[] = [];
+  const failures: OwnedNotificationFailure[] = [];
+  for (const entry of entries) {
+    if (scheduled.length >= capacity) {
+      failures.push({ code: 'schedule_limit', logicalId: entry.logicalId });
+      continue;
+    }
+    try {
+      await platform.schedule(scheduleRequest(namespace, entry));
+      scheduled.push(entry.logicalId);
+    } catch {
+      failures.push({ code: 'schedule_failed', logicalId: entry.logicalId });
+    }
+  }
+  return { scheduled, failures };
+}
+
+async function permissionFailure<TContent>(
+  platform: NotificationPlatform<TContent>,
+): Promise<OwnedNotificationFailureCode | null> {
+  try {
+    return (await platform.permission()) === 'granted' ? null : 'permission_denied';
+  } catch {
+    return 'permission_failed';
+  }
+}
+
+function scheduleRequest<TContent>(
+  namespace: string,
+  entry: OwnedNotification<TContent>,
+): OwnedNotificationScheduleRequest<TContent> {
+  return {
+    identifier: ownedNotificationIdentifier(namespace, entry.logicalId),
+    marker: {
+      namespace,
+      logicalId: entry.logicalId,
+      epochMilliseconds: entry.epochMilliseconds,
+      contentDigest: entry.contentDigest,
+    },
+    content: entry.content,
+  };
+}
+
+function outcome(
+  kept: readonly string[],
+  cancelled: readonly string[],
+  scheduled: readonly string[],
+  failures: readonly OwnedNotificationFailure[],
+): OwnedNotificationReplacementOutcome {
+  return {
+    status: failures.length === 0 ? 'complete' : 'incomplete',
+    kept,
+    cancelled,
+    scheduled,
+    failures,
+  };
+}
+
+function isPositiveInteger(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0;
+}

package/src/validation.ts

@@ -0,0 +1,90 @@
+import { NotificationPlanError } from './errors.js';
+
+export const MAX_NAMESPACE_LENGTH = 64;
+export const MAX_LOGICAL_ID_LENGTH = 128;
+export const MAX_CONTENT_DIGEST_LENGTH = 128;
+
+const NAMESPACE_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const VISIBLE_ASCII_PATTERN = /^[!-~]+$/;
+
+export interface PlannedNotification {
+  readonly logicalId: string;
+  readonly epochMilliseconds: number;
+  readonly contentDigest: string;
+}
+
+export function isValidNamespace(namespace: unknown): namespace is string {
+  return (
+    typeof namespace === 'string' &&
+    namespace.length <= MAX_NAMESPACE_LENGTH &&
+    NAMESPACE_PATTERN.test(namespace)
+  );
+}
+
+export function isValidLogicalId(logicalId: unknown): logicalId is string {
+  return isVisibleAscii(logicalId, MAX_LOGICAL_ID_LENGTH);
+}
+
+export function isValidContentDigest(contentDigest: unknown): contentDigest is string {
+  return isVisibleAscii(contentDigest, MAX_CONTENT_DIGEST_LENGTH);
+}
+
+export function isValidInstant(epochMilliseconds: unknown): epochMilliseconds is number {
+  return (
+    typeof epochMilliseconds === 'number' &&
+    Number.isSafeInteger(epochMilliseconds) &&
+    !Number.isNaN(new Date(epochMilliseconds).getTime())
+  );
+}
+
+export function assertNamespace(namespace: unknown): asserts namespace is string {
+  if (!isValidNamespace(namespace)) {
+    throw new NotificationPlanError('invalid_namespace');
+  }
+}
+
+export function assertIdentity(
+  entry: { readonly logicalId: unknown; readonly contentDigest: unknown },
+  seen: Set<string>,
+): void {
+  if (!isValidLogicalId(entry.logicalId)) {
+    throw new NotificationPlanError('invalid_logical_id');
+  }
+  if (!isValidContentDigest(entry.contentDigest)) {
+    throw new NotificationPlanError('invalid_content_digest', entry.logicalId);
+  }
+  if (seen.has(entry.logicalId)) {
+    throw new NotificationPlanError('duplicate_logical_id', entry.logicalId);
+  }
+  seen.add(entry.logicalId);
+}
+
+export function assertPlannedNotifications(entries: readonly PlannedNotification[]): void {
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    assertIdentity(entry, seen);
+    if (!isValidInstant(entry.epochMilliseconds)) {
+      throw new NotificationPlanError('invalid_instant', entry.logicalId);
+    }
+  }
+}
+
+export function compareByInstant(left: PlannedNotification, right: PlannedNotification): number {
+  return (
+    left.epochMilliseconds - right.epochMilliseconds ||
+    compareCodeUnits(left.logicalId, right.logicalId)
+  );
+}
+
+export function compareCodeUnits(left: string, right: string): number {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function isVisibleAscii(value: unknown, maxLength: number): value is string {
+  return (
+    typeof value === 'string' && value.length <= maxLength && VISIBLE_ASCII_PATTERN.test(value)
+  );
+}