@owlmeans/server-planning 0.1.18-rc.21 → 0.1.18-rc.23

package/src/facade.ts

@@ -1,4 +1,4 @@
-import { criteriaOf, currentSpecification, isProject, isSpecification, linkWhereOf, listOptionsOf, modelOf, projectOf, PlanningUnsupported, specCriteriaOf, transitionWhereOf, WorkcardKind, WorkcardNotFound, type CommitEvent, type CommitSource, type PlanningFacade, type PlanningScope, type Relationship, type Specification, type Transition, type Workcard, type WorkcardModel, type WorkcardQuery } from '@owlmeans/planning'
+import { cardHelper, modelOf, PlanningUnsupported, queryHelper, specificationHelper, WorkcardKind, WorkcardNotFound, type CommitEvent, type CommitSource, type PlanningFacade, type PlanningScope, type Relationship, type Specification, type Transition, type Workcard, type WorkcardModel, type WorkcardQuery } from '@owlmeans/planning'
 import type { Criteria } from '@owlmeans/resource'
 import { makeDefinitions } from './definitions.js'
 import { executeTransition } from './executor.js'
@@ -54,7 +54,7 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
     if (card == null || inProjects(card)) {
       return card
     }
-    if (isSpecification(card) && card.parent != null) {
+    if (cardHelper.isSpecification(card) && card.parent != null) {
       const parent = mine(await reader().cards.get(card.parent, entityId))
       return parent != null && inProjects(parent) ? card : null
     }
@@ -82,7 +82,7 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
 
   /** A narrowed list's or count's criteria — `through` as {@link throughOf} resolved it. */
   const narrowed = async (query?: WorkcardQuery | null): Promise<Criteria<Workcard>> => {
-    const where = criteriaOf(query, scope)
+    const where = queryHelper.criteriaOf(query, scope)
     return narrow(where, await throughOf(where, query?.parent))
   }
 
@@ -121,11 +121,11 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
 
   /** The project a card resolves its data-defined types in. */
   const projectFor = async (card: Workcard): Promise<string | undefined> => {
-    if (isProject(card) || card.parent == null) {
-      return projectOf(card)
+    if (cardHelper.isProject(card) || card.parent == null) {
+      return cardHelper.projectOf(card)
     }
     const parent = mine(await reader().cards.get(card.parent, entityId))
-    return projectOf(card, parent)
+    return cardHelper.projectOf(card, parent)
   }
 
   const facade: PlanningFacade = {
@@ -144,13 +144,13 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
         return card
       },
 
-      list: async query => await reader().cards.list(await narrowed(query), listOptionsOf(query)),
+      list: async query => await reader().cards.list(await narrowed(query), queryHelper.listOptionsOf(query)),
 
       count: async query => await reader().cards.count(await narrowed(query)),
 
       summary: async (parents, query) => parents.length === 0
         ? {}
-        : await reader().cards.summary(parents, narrow(criteriaOf({ kind: query?.kind, type: query?.type }, scope))),
+        : await reader().cards.summary(parents, narrow(queryHelper.criteriaOf({ kind: query?.kind, type: query?.type }, scope))),
     },
 
     specifications: {
@@ -162,8 +162,8 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
         if (specs != null) {
           return mine(await specs.current(parent, category, entityId))
         }
-        const listed = await reader().cards.list(specCriteriaOf(parent, { category }, scope) as never, { size: 0 })
-        return currentSpecification(listed.items, category)
+        const listed = await reader().cards.list(queryHelper.specCriteriaOf(parent, { category }, scope) as never, { size: 0 })
+        return specificationHelper.currentSpecification(listed.items, category)
       },
 
       list: async (parent, query) => {
@@ -174,12 +174,12 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
         if (specs != null) {
           return await specs.list(parent, entityId, query)
         }
-        return await reader().cards.list(specCriteriaOf(parent, query, scope) as never, listOptionsOf(query) as never) as never
+        return await reader().cards.list(queryHelper.specCriteriaOf(parent, query, scope) as never, queryHelper.listOptionsOf(query) as never) as never
       },
 
       get: async id => {
         const card = await facade.cards.load(id)
-        if (card == null || !isSpecification(card)) {
+        if (card == null || !cardHelper.isSpecification(card)) {
           throw new WorkcardNotFound(id)
         }
         return card as Specification
@@ -202,9 +202,9 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
           return { items: [], total: 0 }
         }
         if (projects == null) {
-          return await links.list(linkWhereOf(query, scope), listOptionsOf(query))
+          return await links.list(queryHelper.linkWhereOf(query, scope), queryHelper.listOptionsOf(query))
         }
-        const listed = await links.list({ ...linkWhereOf(query, scope), project: projects }, listOptionsOf(query))
+        const listed = await links.list({ ...queryHelper.linkWhereOf(query, scope), project: projects }, queryHelper.listOptionsOf(query))
         // A store that ignores `project` must still not leak an edge filed under another project.
         const items = listed.items.filter((link: Relationship) => projectVisible(link.project))
         return items.length === listed.items.length ? listed : { ...listed, items, total: listed.total - (listed.items.length - items.length) }
@@ -226,13 +226,13 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
           return { items: [], total: 0 }
         }
         if (projects == null) {
-          return await transitions.list(transitionWhereOf(query, scope), listOptionsOf(query))
+          return await transitions.list(queryHelper.transitionWhereOf(query, scope), queryHelper.listOptionsOf(query))
         }
         if (query.project != null && !projects.includes(query.project)) {
           return { items: [], total: 0 }
         }
         const listed = await transitions.list(
-          { ...transitionWhereOf(query, scope), project: query.project ?? projects }, listOptionsOf(query)
+          { ...queryHelper.transitionWhereOf(query, scope), project: query.project ?? projects }, queryHelper.listOptionsOf(query)
         )
         const items = listed.items.filter((transition: Transition) => projectVisible(transition.project))
         return items.length === listed.items.length ? listed : { ...listed, items, total: listed.total - (listed.items.length - items.length) }

package/src/helper.ts

@@ -8,7 +8,7 @@ import {
   watchCommits,
 } from './actions/index.js'
 import type { PlanningHandlerOptions } from './types.js'
-import { planningServiceOf, scopeOf } from './utils/index.js'
+import { planningHandlerOf } from './utils/handler.js'
 
 /**
  * Bind this package's handlers to a tree declared by `makePlanningProtocols` — one binding per
@@ -36,13 +36,8 @@ export const servePlanningEntrypoints = (protocols: PlanningProtocols, opts?: Pl
   bind(protocols.commit.events, watchCommits(protocols.commit.events, opts)),
 ]
 
-/**
- * The facade a hand-written handler works through: the request's entity and subject, plus `extra`
- * (a `channel`) — never an entity from the request body.
- *
- * @throws {AuthorizationError} when the request carries no organization
- */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).planningFor(…)` */
 export const planningFor = (
   ctx: BasicContext<BasicConfig>, req: AbstractRequest, extra?: Partial<PlanningScope>,
   opts?: Pick<PlanningHandlerOptions, 'service'>
-): PlanningFacade => planningServiceOf(ctx, opts).for(scopeOf(req, extra))
+): PlanningFacade => planningHandlerOf(ctx).planningFor(req, extra, opts)

package/src/projection.ts

@@ -3,7 +3,7 @@ import { PLANNING_SERVICE, type PlanningService, type PlanningStore } from '@owl
 import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from './queue/consts.js'
 import type { ProjectionRequest } from './queue/types.js'
 import type { JobProcessor, QueueHooks } from '@owlmeans/queue'
-import { failPending, foldPending } from './store/fold.js'
+import { foldHelper } from './store/fold.js'
 import type { PlanningHostService, ProjectionOptions } from './types.js'
 import type { CommitHub, FoldResult } from './store/types.js'
 
@@ -30,7 +30,7 @@ export const makeProjectionProcessor = (
   const store = storeOf(service, opts)
   const publish = publisherOf(store, opts)
 
-  return await foldPending(store, job.data.cardId, job.data.entityId, {
+  return await foldHelper.foldPending(store, job.data.cardId, job.data.entityId, {
     touch: job.touch,
     onCommitted: async event => { await service.committed(event) },
     ...(publish != null ? { publish } : {}),
@@ -42,7 +42,7 @@ export const makeProjectionProcessor = (
  * failed event is published — otherwise `execute({ wait: true })` and `commits.wait` hang to their
  * timeout. Merge it into the queue driver's hooks.
  */
-export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks => ({
+export const makePlanningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks => ({
   onJobDead: async (job, reason) => {
     if (job.queue !== PLANNING_PROJECTION_QUEUE || job.name !== PLANNING_PROJECT_JOB) {
       return
@@ -50,6 +50,10 @@ export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: Projec
     const request = job.data as ProjectionRequest
     const store = storeOf(serviceOf(ctx, opts), opts)
     const publish = publisherOf(store, opts)
-    await failPending(store, request.cardId, request.entityId, reason, publish != null ? { publish } : {})
+    await foldHelper.failPending(store, request.cardId, request.entityId, reason, publish != null ? { publish } : {})
   },
 })
+
+/** @deprecated compat:factory-refactor — use `makePlanningQueueHooks(…)` */
+export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks =>
+  makePlanningQueueHooks(ctx, opts)

package/src/queue/declare.ts

@@ -0,0 +1,7 @@
+import { declareQueue, type Config } from '@owlmeans/queue'
+import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from './consts.js'
+import type { PlanningQueueOptions } from './types.js'
+
+/** Declare the shared projection address; each process separately chooses whether to listen. */
+export const declarePlanningQueue = <C extends Config>(cfg: C, opts?: PlanningQueueOptions): C =>
+  declareQueue(cfg, PLANNING_PROJECTION_QUEUE, [PLANNING_PROJECT_JOB], opts)

package/src/queue/index.ts

@@ -1,10 +1,3 @@
-import { declareQueue, type Config } from '@owlmeans/queue'
-import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from './consts.js'
-import type { PlanningQueueOptions } from './types.js'
-
-/** Declare the shared projection address; each process separately chooses whether to listen. */
-export const declarePlanningQueue = <C extends Config>(cfg: C, opts?: PlanningQueueOptions): C =>
-  declareQueue(cfg, PLANNING_PROJECTION_QUEUE, [PLANNING_PROJECT_JOB], opts)
-
+export { declarePlanningQueue } from './declare.js'
 export { PLANNING_PROJECTION_QUEUE, PLANNING_PROJECT_JOB } from './consts.js'
 export type { PlanningQueueOptions, ProjectionRequest } from './types.js'

package/src/store/composite.ts

@@ -3,9 +3,9 @@ import type {
   CommitSource, PlanningStore, ProjectionStore, Relationship, RelationshipStore, SpecificationStore,
   TransitionStore, Unsubscribe, Workcard,
 } from '@owlmeans/planning'
-import { applyQuery } from '@owlmeans/resource'
 import type { Criteria, ListResult } from '@owlmeans/resource'
 import type { CommitHub, StoreRoute } from './types.js'
+import { recordQueryHelper } from '@owlmeans/resource'
 
 const firstOf = async <S, T>(
   stores: S[], read: (store: S) => Promise<T | null | undefined> | undefined
@@ -122,7 +122,7 @@ export const makeCompositeStore = (routes: StoreRoute[], fallback: PlanningStore
     list: async (where, opts) => {
       const results = await Promise.all(linked.map(store => store.links!.list(where, { size: 0 })))
       const items = results.flatMap((result: ListResult<Relationship>) => result.items)
-      return applyQuery(items, undefined, opts)
+      return recordQueryHelper.applyQuery(items, undefined, opts)
     },
     put: link => (fallback.links ?? linked[0].links!).put(link),
     drop: where => sum(linked, store => store.links!.drop(where)),

package/src/store/fold/types.ts

@@ -0,0 +1,44 @@
+import type { CommitEvent, CommitState, PlanningStore, SpecificationRevision, Transition, Workcard } from '@owlmeans/planning'
+import type { FoldOptions, FoldResult } from '../types.js'
+
+/** The projection body every store reuses: the fold of a card's pending log, and what it publishes. */
+export interface FoldHelper {
+  /** The event a settled transition publishes. `record` is in-process only — strip it before a bus. */
+  commitEventOf: (
+    transition: Transition, state: CommitState, at: string, extra?: { error?: string, record?: Workcard | null }
+  ) => CommitEvent
+  /**
+   * Fold every pending transition of one card — the projection body every store reuses.
+   *
+   * Transitions are read in `seq` order past the card's own `seq`, and only `pending` ones are
+   * applied, each with `applyHelper.applyTransition` and nothing else. Per transition: write the
+   * record (a `delete` drops it, a project `delete` purges everything under it), fold its
+   * relationships, mark it `committed`, `publish` the event, then run `onCommitted` — so the `after`
+   * chain runs in THIS process, exactly once per committed transition. A transition that cannot be
+   * folded is marked `failed` with the reason and a failed event is published, and the fold goes PAST
+   * it: the card's `seq` advances to the failed transition with every other value as it was, so the
+   * next transition applies normally. Nothing is removed from the log. A create that fails leaves no
+   * card to advance, so what follows it fails too; a store that refuses the advancing write itself
+   * stops the fold there and reports `followUp`, leaving the rest pending for a retry.
+   *
+   * The caller owns single flight: two folds of one card running at once would both publish. A
+   * transactional store passes `unit`, which wraps each transition's writes (a savepoint), so a write
+   * the database refuses is undone whole before the fold marks the transition failed.
+   *
+   * @throws {PlanningUnsupported} for a store without a transition log
+   */
+  foldPending: (store: PlanningStore, cardId: string, entityId: string, opts?: FoldOptions) => Promise<FoldResult>
+  /**
+   * Mark every pending transition of a card `failed` and publish a failed event for each — what a
+   * queued store does when its projection job is dead, or waiters hang until their timeout.
+   */
+  failPending: (
+    store: PlanningStore, cardId: string, entityId: string, reason: string, opts?: Pick<FoldOptions, 'publish' | 'now'>
+  ) => Promise<number>
+  /**
+   * A specification's history, replayed from its log: one entry per create and per committed
+   * content change, newest first. The fold is `applyHelper.applyTransition` itself, so an entry's
+   * `body` is the body AT that revision even when the transition changed only `ref`.
+   */
+  revisionsFromLog: (log: Transition[], limit?: number) => SpecificationRevision[]
+}