@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.21

package/src/helpers/apply.ts

@@ -1,183 +1,166 @@
 import { IntrinsicStatus, TransitionAction } from '../consts.js'
 import { PlanningError } from '../errors.js'
 import type { Relationship, RelationshipDraft, Transition, Workcard } from '../types.js'
-
-/** Never written by a transition's `changes`: the fold takes them from the transition itself. */
-const IDENTITY_KEYS = new Set(['id', 'kind', 'type', 'entityId', 'seq', 'head', 'createdAt'])
-
-/** Cannot be cleared: a record without them is not a record. */
-const REQUIRED_KEYS = new Set([
-  ...IDENTITY_KEYS, 'title', 'parents', 'status', 'intrinsic', 'flows', 'labels', 'fields',
-])
-
-/** Merged shallowly into the card's own map rather than replacing it. */
-const MERGED_KEYS = new Set(['fields', 'flows'])
+import type { ApplyHelper } from './apply/types.js'
+import { IDENTITY_KEYS, MERGED_KEYS, REQUIRED_KEYS } from './apply/consts.local.js'
 
 const clean = <T extends object>(record: T): T =>
   Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
 
-const outOfOrder = (card: Workcard | null | undefined, transition: Transition): PlanningError =>
-  new PlanningError(`fold:out-of-order:${transition.card}:${card?.seq ?? 0}:${transition.seq}`)
-
-const unsetOn = (record: Record<string, unknown>, paths: string[] | undefined): void => {
-  for (const path of paths ?? []) {
-    const dot = path.indexOf('.')
-    if (dot > 0) {
-      const head = path.slice(0, dot)
-      const map = record[head]
-      if (MERGED_KEYS.has(head) && map != null && typeof map === 'object') {
-        delete (map as Record<string, unknown>)[path.slice(dot + 1)]
+export const createApplyHelper = (): ApplyHelper => {
+  const outOfOrder = (card: Workcard | null | undefined, transition: Transition): PlanningError =>
+    new PlanningError(`fold:out-of-order:${transition.card}:${card?.seq ?? 0}:${transition.seq}`)
+
+  const unsetOn = (record: Record<string, unknown>, paths: string[] | undefined): void => {
+    for (const path of paths ?? []) {
+      const dot = path.indexOf('.')
+      if (dot > 0) {
+        const head = path.slice(0, dot)
+        const map = record[head]
+        if (MERGED_KEYS.has(head) && map != null && typeof map === 'object') {
+          delete (map as Record<string, unknown>)[path.slice(dot + 1)]
+        }
+        continue
+      }
+      if (!REQUIRED_KEYS.has(path)) {
+        delete record[path]
       }
-      continue
-    }
-    if (!REQUIRED_KEYS.has(path)) {
-      delete record[path]
     }
   }
-}
 
-const writeChanges = (record: Record<string, unknown>, changes: Record<string, unknown>): void => {
-  for (const [key, value] of Object.entries(changes)) {
-    if (value === undefined || IDENTITY_KEYS.has(key)) {
-      continue
-    }
-    if (MERGED_KEYS.has(key)) {
-      const merged = { ...(record[key] as Record<string, unknown> | undefined ?? {}) }
-      for (const [entry, entryValue] of Object.entries(value as Record<string, unknown> ?? {})) {
-        if (entryValue === null) {
-          delete merged[entry]
-        } else if (entryValue !== undefined) {
-          merged[entry] = entryValue
+  const writeChanges = (record: Record<string, unknown>, changes: Record<string, unknown>): void => {
+    for (const [key, value] of Object.entries(changes)) {
+      if (value === undefined || IDENTITY_KEYS.has(key)) {
+        continue
+      }
+      if (MERGED_KEYS.has(key)) {
+        const merged = { ...(record[key] as Record<string, unknown> | undefined ?? {}) }
+        for (const [entry, entryValue] of Object.entries(value as Record<string, unknown> ?? {})) {
+          if (entryValue === null) {
+            delete merged[entry]
+          } else if (entryValue !== undefined) {
+            merged[entry] = entryValue
+          }
         }
+        record[key] = merged
+        continue
       }
-      record[key] = merged
-      continue
-    }
-    if (value === null) {
-      if (!REQUIRED_KEYS.has(key)) {
-        delete record[key]
+      if (value === null) {
+        if (!REQUIRED_KEYS.has(key)) {
+          delete record[key]
+        }
+        continue
       }
-      continue
+      record[key] = value
     }
-    record[key] = value
   }
-}
 
-/**
- * THE fold: the card after one transition. Pure, total, no I/O — every store (memory, Mongo, a
- * client mirror) folds with this and nothing else, so one log always means one card.
- *
- * - An already-applied transition (`seq <= card.seq`) returns the card unchanged: re-folding is
- *   safe.
- * - Anything but the next seq (`card.seq + 1`, or 1 for a create with no card) is refused with
- *   `PlanningError('fold:out-of-order')`.
- * - `create` builds the whole record from `changes` plus the transition's identity; `delete`
- *   answers `null`; `link`/`unlink` only move `seq`/`head`/`updatedAt` (the edges are
- *   {@link applyRelationship}'s); `update`/`transit` write `changes` — `fields` and `flows` merge,
- *   everything else replaces — and clear `unset`.
- * - Every result has `seq = transition.seq`, `head = max(head, seq)`, `updatedAt = transition.at`.
- *
- * @throws {PlanningError} `planning:fold:out-of-order:…`
- */
-export const applyTransition = <T extends Workcard = Workcard>(
-  card: T | null | undefined, transition: Transition
-): T | null => {
-  if (card != null && transition.seq <= card.seq) {
-    return card
-  }
-  if (card == null) {
-    if (transition.action === TransitionAction.Delete) {
-      return null
+  const applyTransition = <T extends Workcard = Workcard>(
+    card: T | null | undefined, transition: Transition
+  ): T | null => {
+    if (card != null && transition.seq <= card.seq) {
+      return card
     }
-    if (transition.action !== TransitionAction.Create || transition.seq !== 1) {
+    if (card == null) {
+      if (transition.action === TransitionAction.Delete) {
+        return null
+      }
+      if (transition.action !== TransitionAction.Create || transition.seq !== 1) {
+        throw outOfOrder(card, transition)
+      }
+    } else if (transition.seq !== card.seq + 1) {
       throw outOfOrder(card, transition)
     }
-  } else if (transition.seq !== card.seq + 1) {
-    throw outOfOrder(card, transition)
-  }
 
-  if (transition.action === TransitionAction.Delete) {
-    return null
-  }
+    if (transition.action === TransitionAction.Delete) {
+      return null
+    }
+
+    const head = Math.max(card?.head ?? card?.seq ?? 0, transition.seq)
+    const changes = structuredClone(transition.changes ?? {}) as Record<string, unknown>
 
-  const head = Math.max(card?.head ?? card?.seq ?? 0, transition.seq)
-  const changes = structuredClone(transition.changes ?? {}) as Record<string, unknown>
+    if (transition.action === TransitionAction.Create) {
+      const record: Record<string, unknown> = {
+        parents: [], labels: [], fields: {}, flows: {}, status: '', intrinsic: IntrinsicStatus.Planned,
+      }
+      writeChanges(record, changes)
+      unsetOn(record, transition.unset)
+
+      return clean({
+        ...record,
+        id: transition.card,
+        kind: transition.kind,
+        type: transition.type,
+        entityId: transition.entityId,
+        seq: transition.seq,
+        head,
+        createdAt: transition.at,
+        updatedAt: transition.at,
+      }) as unknown as T
+    }
 
-  if (transition.action === TransitionAction.Create) {
-    const record: Record<string, unknown> = {
-      parents: [], labels: [], fields: {}, flows: {}, status: '', intrinsic: IntrinsicStatus.Planned,
+    const record = structuredClone(card) as unknown as Record<string, unknown>
+    if (transition.action === TransitionAction.Update || transition.action === TransitionAction.Transit) {
+      writeChanges(record, changes)
+      unsetOn(record, transition.unset)
     }
-    writeChanges(record, changes)
-    unsetOn(record, transition.unset)
-
-    return clean({
-      ...record,
-      id: transition.card,
-      kind: transition.kind,
-      type: transition.type,
-      entityId: transition.entityId,
-      seq: transition.seq,
-      head,
-      createdAt: transition.at,
-      updatedAt: transition.at,
-    }) as unknown as T
-  }
+    record.seq = transition.seq
+    record.head = head
+    record.updatedAt = transition.at
 
-  const record = structuredClone(card) as unknown as Record<string, unknown>
-  if (transition.action === TransitionAction.Update || transition.action === TransitionAction.Transit) {
-    writeChanges(record, changes)
-    unsetOn(record, transition.unset)
+    return clean(record) as unknown as T
   }
-  record.seq = transition.seq
-  record.head = head
-  record.updatedAt = transition.at
-
-  return clean(record) as unknown as T
-}
 
-const edgeOf = (transition: Transition, draft: RelationshipDraft): Relationship => clean({
-  entityId: transition.entityId,
-  type: draft.type,
-  from: draft.from ?? transition.card,
-  to: draft.to,
-  project: transition.project,
-  fields: draft.fields == null ? undefined : structuredClone(draft.fields),
-  createdAt: transition.at,
-  transition: transition.id,
-})
-
-const sameEdge = (left: Pick<Relationship, 'entityId' | 'from' | 'to' | 'type'>, right: Pick<Relationship, 'entityId' | 'from' | 'to' | 'type'>): boolean =>
-  left.entityId === right.entityId && left.from === right.from && left.to === right.to && left.type === right.type
-
-/**
- * The relationships after one transition. Pure and total, like {@link applyTransition}.
- *
- * `create` adds its `links`, `link` adds its `link`, `unlink` removes the matching edge, and a
- * `delete` removes every edge touching the card. An edge that already exists is kept as it is, so
- * re-folding adds nothing. Every other action answers the list unchanged. Always a new array.
- */
-export const applyRelationship = (links: Relationship[], transition: Transition): Relationship[] => {
-  const add = (drafts: RelationshipDraft[]): Relationship[] => drafts.reduce((result, draft) => {
-    const edge = edgeOf(transition, draft)
-    return result.some(existing => sameEdge(existing, edge)) ? result : [...result, edge]
-  }, [...links])
-
-  switch (transition.action) {
-    case TransitionAction.Create:
-      return add(transition.links ?? [])
-    case TransitionAction.Link:
-      return add(transition.link == null ? [] : [transition.link])
-    case TransitionAction.Unlink: {
-      if (transition.link == null) {
-        return [...links]
+  const edgeOf = (transition: Transition, draft: RelationshipDraft): Relationship => clean({
+    entityId: transition.entityId,
+    type: draft.type,
+    from: draft.from ?? transition.card,
+    to: draft.to,
+    project: transition.project,
+    fields: draft.fields == null ? undefined : structuredClone(draft.fields),
+    createdAt: transition.at,
+    transition: transition.id,
+  })
+
+  const sameEdge = (left: Pick<Relationship, 'entityId' | 'from' | 'to' | 'type'>, right: Pick<Relationship, 'entityId' | 'from' | 'to' | 'type'>): boolean =>
+    left.entityId === right.entityId && left.from === right.from && left.to === right.to && left.type === right.type
+
+  const applyRelationship = (links: Relationship[], transition: Transition): Relationship[] => {
+    const add = (drafts: RelationshipDraft[]): Relationship[] => drafts.reduce((result, draft) => {
+      const edge = edgeOf(transition, draft)
+      return result.some(existing => sameEdge(existing, edge)) ? result : [...result, edge]
+    }, [...links])
+
+    switch (transition.action) {
+      case TransitionAction.Create:
+        return add(transition.links ?? [])
+      case TransitionAction.Link:
+        return add(transition.link == null ? [] : [transition.link])
+      case TransitionAction.Unlink: {
+        if (transition.link == null) {
+          return [...links]
+        }
+        const edge = edgeOf(transition, transition.link)
+        return links.filter(existing => !sameEdge(existing, edge))
       }
-      const edge = edgeOf(transition, transition.link)
-      return links.filter(existing => !sameEdge(existing, edge))
+      case TransitionAction.Delete:
+        return links.filter(existing => existing.entityId !== transition.entityId
+          || (existing.from !== transition.card && existing.to !== transition.card))
+      default:
+        return [...links]
     }
-    case TransitionAction.Delete:
-      return links.filter(existing => existing.entityId !== transition.entityId
-        || (existing.from !== transition.card && existing.to !== transition.card))
-    default:
-      return [...links]
   }
+
+  return { applyTransition, applyRelationship }
 }
+
+export const applyHelper = createApplyHelper()
+
+/** @deprecated compat:factory-refactor — use `applyHelper.applyTransition(…)` */
+export const applyTransition = <T extends Workcard = Workcard>(
+  card: T | null | undefined, transition: Transition
+): T | null => applyHelper.applyTransition<T>(card, transition)
+
+/** @deprecated compat:factory-refactor — use `applyHelper.applyRelationship(…)` */
+export const applyRelationship = (links: Relationship[], transition: Transition): Relationship[] =>
+  applyHelper.applyRelationship(links, transition)

package/src/helpers/card/types.ts

@@ -0,0 +1,20 @@
+import type { Card, Project, Specification, Workcard, WorkcardDraft } from '../../types.js'
+
+/** The kind guards and the parent rules every record keeps. */
+export interface CardHelper {
+  isProject: (card?: Workcard | null) => card is Project
+  isCard: (card?: Workcard | null) => card is Card
+  isSpecification: (card?: Workcard | null) => card is Specification
+  /** `parents` with `parent` first and no repeats — the invariant every record keeps. */
+  normalizeParents: (parent?: string | null, parents?: string[] | null) => string[]
+  /** A draft with the collections every record carries filled in. */
+  cardDefaults: (draft: WorkcardDraft) => WorkcardDraft & Required<Pick<WorkcardDraft, 'parents' | 'labels' | 'fields'>>
+  /** A transition was allocated for the card and has not been folded yet. */
+  isPending: (card: Pick<Workcard, 'seq' | 'head'>) => boolean
+  parentOf: (card: Workcard) => string | undefined
+  /**
+   * The project a card belongs to: a project is its own; a card under a project is that project's;
+   * anything deeper is its parent's project, which needs the parent to answer.
+   */
+  projectOf: (card: Workcard, parent?: Workcard | null) => string | undefined
+}

package/src/helpers/card.ts

@@ -1,42 +1,68 @@
 import { WorkcardKind } from '../consts.js'
 import type { Card, Project, Specification, Workcard, WorkcardDraft } from '../types.js'
+import type { CardHelper } from './card/types.js'
 
-export const isProject = (card?: Workcard | null): card is Project => card?.kind === WorkcardKind.Project
+export const createCardHelper = (): CardHelper => {
+  const isProject = (card?: Workcard | null): card is Project => card?.kind === WorkcardKind.Project
 
-export const isCard = (card?: Workcard | null): card is Card => card?.kind === WorkcardKind.Card
+  const isCard = (card?: Workcard | null): card is Card => card?.kind === WorkcardKind.Card
 
-export const isSpecification = (card?: Workcard | null): card is Specification =>
-  card?.kind === WorkcardKind.Specification
+  const isSpecification = (card?: Workcard | null): card is Specification =>
+    card?.kind === WorkcardKind.Specification
 
-/** `parents` with `parent` first and no repeats — the invariant every record keeps. */
-export const normalizeParents = (parent?: string | null, parents?: string[] | null): string[] =>
-  [...new Set([...(parent != null && parent !== '' ? [parent] : []), ...(parents ?? [])])]
-    .filter(id => id !== '')
-
-/** A draft with the collections every record carries filled in. */
-export const cardDefaults = (draft: WorkcardDraft): WorkcardDraft & Required<Pick<WorkcardDraft, 'parents' | 'labels' | 'fields'>> => ({
-  ...draft,
-  parents: normalizeParents(draft.parent, draft.parents),
-  labels: [...new Set(draft.labels ?? [])],
-  fields: draft.fields ?? {},
-})
-
-/** A transition was allocated for the card and has not been folded yet. */
-export const isPending = (card: Pick<Workcard, 'seq' | 'head'>): boolean => (card.head ?? card.seq) > card.seq
-
-export const parentOf = (card: Workcard): string | undefined => card.parent ?? card.parents[0]
-
-/**
- * The project a card belongs to: a project is its own; a card under a project is that project's;
- * anything deeper is its parent's project, which needs the parent to answer.
- */
-export const projectOf = (card: Workcard, parent?: Workcard | null): string | undefined => {
-  if (isProject(card)) {
-    return card.id
-  }
-  if (parent != null) {
-    return isProject(parent) ? parent.id : parent.parent
+  const normalizeParents = (parent?: string | null, parents?: string[] | null): string[] =>
+    [...new Set([...(parent != null && parent !== '' ? [parent] : []), ...(parents ?? [])])]
+      .filter(id => id !== '')
+
+  const cardDefaults = (draft: WorkcardDraft): WorkcardDraft & Required<Pick<WorkcardDraft, 'parents' | 'labels' | 'fields'>> => ({
+    ...draft,
+    parents: normalizeParents(draft.parent, draft.parents),
+    labels: [...new Set(draft.labels ?? [])],
+    fields: draft.fields ?? {},
+  })
+
+  const isPending = (card: Pick<Workcard, 'seq' | 'head'>): boolean => (card.head ?? card.seq) > card.seq
+
+  const parentOf = (card: Workcard): string | undefined => card.parent ?? card.parents[0]
+
+  const projectOf = (card: Workcard, parent?: Workcard | null): string | undefined => {
+    if (isProject(card)) {
+      return card.id
+    }
+    if (parent != null) {
+      return isProject(parent) ? parent.id : parent.parent
+    }
+
+    return card.parent
   }
 
-  return card.parent
+  return { isProject, isCard, isSpecification, normalizeParents, cardDefaults, isPending, parentOf, projectOf }
 }
+
+export const cardHelper = createCardHelper()
+
+/** @deprecated compat:factory-refactor — use `cardHelper.isProject(…)` */
+export const isProject = (card?: Workcard | null): card is Project => cardHelper.isProject(card)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.isCard(…)` */
+export const isCard = (card?: Workcard | null): card is Card => cardHelper.isCard(card)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.isSpecification(…)` */
+export const isSpecification = (card?: Workcard | null): card is Specification => cardHelper.isSpecification(card)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.normalizeParents(…)` */
+export const normalizeParents = (parent?: string | null, parents?: string[] | null): string[] =>
+  cardHelper.normalizeParents(parent, parents)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.cardDefaults(…)` */
+export const cardDefaults = (draft: WorkcardDraft): WorkcardDraft & Required<Pick<WorkcardDraft, 'parents' | 'labels' | 'fields'>> =>
+  cardHelper.cardDefaults(draft)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.isPending(…)` */
+export const isPending = (card: Pick<Workcard, 'seq' | 'head'>): boolean => cardHelper.isPending(card)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.parentOf(…)` */
+export const parentOf = (card: Workcard): string | undefined => cardHelper.parentOf(card)
+
+/** @deprecated compat:factory-refactor — use `cardHelper.projectOf(…)` */
+export const projectOf = (card: Workcard, parent?: Workcard | null): string | undefined => cardHelper.projectOf(card, parent)

package/src/helpers/changes/consts.local.ts

@@ -0,0 +1,17 @@
+/** Never in a caller's changes: the transition itself carries them. */
+export const IDENTITY_KEYS = ['id', 'kind', 'type', 'entityId', 'seq', 'head', 'createdAt']
+
+/** Written once, from a create's draft; never by `changes` or `unset`, whatever the action. */
+export const PROVENANCE_KEYS = ['createdBy']
+
+/** Move only through `transit` (or a create's draft). */
+export const FLOW_KEYS = ['status', 'intrinsic', 'flows', 'closedAt']
+
+/** Computed by the executor, never supplied. */
+export const DERIVED_KEYS = ['revision', 'bodyChars']
+
+/** Cannot be cleared. */
+export const REQUIRED_KEYS = ['title', 'parents', 'labels', 'fields', 'category', 'format']
+
+/** Changing one of these produces a new revision of a revisioned document. */
+export const CONTENT_KEYS = ['body', 'ref', 'format', 'version']

package/src/helpers/changes/types.ts

@@ -0,0 +1,66 @@
+import type {
+  AnyTypeSchema, SpecificationSlot, TransitionExecution, Workcard, WorkcardChanges,
+} from '../../types.js'
+import type { FlowLookup } from '../types.local.js'
+
+export interface ChangeSet {
+  changes: WorkcardChanges
+  unset: string[]
+  /** Transit only: the flow that moved, and the move. */
+  flow?: string
+  from?: string
+  to?: string
+}
+
+/** What a transition records — computed from an execution, and the guards it must pass first. */
+export interface ChangesHelper {
+  /** Structural equality over JSON values. */
+  sameValue: (left: unknown, right: unknown) => boolean
+  /** A shallow merge that drops keys patched to `null`. */
+  mergeFields: (base?: Record<string, unknown> | null, patch?: Record<string, unknown> | null) => Record<string, unknown>
+  /** A copy of the record with the paths (`key`, `fields.key`, `flows.id`) removed. */
+  applyUnset: <T extends object>(record: T, unset?: string[]) => T
+  /**
+   * Refuse an execution that writes what only the transition, the flow or the executor may write.
+   *
+   * `status`/`intrinsic`/`flows`/`closedAt` move only through `transit` (a create's draft may name
+   * the initial status); `code` is fixed once minted unless the type's policy says `mutable`;
+   * `category` is fixed; `revision`/`bodyChars` are computed; `createdBy` is the create DRAFT's
+   * alone — named in `changes` or `unset` it is refused on every action, so an owner check
+   * (`card.createdBy === profileId`) can trust it.
+   *
+   * @throws {PlanningError} `planning:immutable:<field>`
+   */
+  assertMutable: (exec: TransitionExecution, type: AnyTypeSchema) => void
+  /**
+   * The `changes`/`unset` a transition records (plan step 9).
+   *
+   * - `create`: the whole initial record from the draft (overlaid by `exec.changes`) — `parents`
+   *   normalized, every flow at its initial status (the draft's `status` for the primary one),
+   *   `status`/`intrinsic` mirrored, `closedAt` when it starts closed; a specification gets its
+   *   format, `bodyChars` and revision 1 when the slot is revisioned.
+   * - `update`: only what differs; `null` or `exec.unset` clears a field that has a value; a moved
+   *   `parent` replaces the old one in `parents`; a revisioned document whose content changed gets
+   *   `revision + 1`. An update that changes nothing is empty ({@link ChangesHelper.isEmptyChange}).
+   * - `transit`: `flows[flow] = rule.to`, `status` when the flow is primary, `intrinsic` when it
+   *   moves, `closedAt` set on entering closed and cleared on leaving it — plus the caller's own
+   *   changes, diffed as in an update.
+   * - `link`, `unlink`, `delete`: nothing.
+   *
+   * `createdBy` comes from a create's draft only: `changes` and `unset` never carry it, on any action
+   * ({@link ChangesHelper.assertMutable} refuses an execution that tries).
+   *
+   * @throws {IllegalTransition} a transit the flow does not offer from the current status
+   * @throws {PlanningError} `malformed:*` for an execution missing what its action needs
+   */
+  computeChanges: (
+    card: Workcard | null | undefined,
+    exec: TransitionExecution,
+    type: AnyTypeSchema,
+    registry: FlowLookup,
+    at: string,
+    opts?: { slot?: SpecificationSlot | null }
+  ) => ChangeSet
+  /** Nothing to write: no changed value and nothing to clear. */
+  isEmptyChange: (set: Pick<ChangeSet, 'changes' | 'unset'>) => boolean
+}