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

package/src/registry.ts

@@ -1,34 +1,10 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import { ResilientError } from '@owlmeans/error'
-import { DEFAULT_PLUGIN_ORDER, PlanningRefused } from '@owlmeans/planning'
-import type {
-  CommitEvent, PlanningExecContext, PlanningHookContext, PlanningPlugin, PlanningSchemaRegistry,
-  PlanningStore, TransitionExecution, WorkcardDraft,
-} from '@owlmeans/planning'
-import type { StoreRoute } from './store/types.js'
+import { logger } from '@owlmeans/log'
+import { DEFAULT_PLUGIN_ORDER, PlanningRefused, type PlanningPlugin, type PlanningSchemaRegistry, type PlanningStore } from '@owlmeans/planning'
+import type { PluginRegistry } from './types.js'
 
-export interface PluginRegistry {
-  /** Register, or replace the plugin of the same `name`. Its schemas are contributed now. */
-  use: (plugin: PlanningPlugin) => void
-  /** Every plugin, `order` ascending (registration order among equals). */
-  plugins: () => PlanningPlugin[]
-  /** The owning plugins that supply a store, in plugin order, each store resolved once. */
-  routes: (ctx?: BasicContext<BasicConfig>) => StoreRoute[]
-  /** The first owning plugin's store for a type, else `fallback`. */
-  storeFor: (type: string | undefined, fallback: PlanningStore, ctx?: BasicContext<BasicConfig>) => PlanningStore
-  /** The first plugin answering a code wins. */
-  mintCode: (
-    draft: WorkcardDraft, taken: (code: string) => Promise<boolean>, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
-  ) => Promise<string | undefined>
-  /** The `before` chain; answers the execution the chain left. */
-  before: (
-    exec: TransitionExecution, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
-  ) => Promise<TransitionExecution>
-  /** The `after` chain; a failing hook is logged and the chain goes on. */
-  after: (event: CommitEvent, contextOf: (plugin: PlanningPlugin) => PlanningHookContext) => Promise<void>
-  /** Bumps on every `use` — what a cached composite store is keyed by. */
-  version: () => number
-}
+const log = logger('planning')
 
 const messageOf = (error: unknown): string => error instanceof Error ? error.message : `${error}`
 
@@ -131,7 +107,7 @@ export const makePluginRegistry = (
         try {
           await plugin.after(event, contextOf(plugin))
         } catch (error) {
-          console.error(`planning: after hook of ${plugin.name} failed on ${event.transition}:`, error)
+          log.error('Planning after hook failed', { plugin: plugin.name, transition: event.transition, error })
         }
       }
     },

package/src/service.ts

@@ -1,42 +1,13 @@
-import { createLazyService } from '@owlmeans/context'
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { makeSchemaRegistry, PlanningError } from '@owlmeans/planning'
-import type {
-  PlanningSchemaRegistry, PlanningService, PlanningStore, SchemaStore, ScopedSchemaRegistry, Transition,
-  WithPlanningService,
-} from '@owlmeans/planning'
+import { createLazyService, type BasicConfig, type BasicContext } from '@owlmeans/context'
+import { makeSchemaRegistry, PlanningError, type PlanningService, type PlanningStore, type Transition, type WithPlanningService } from '@owlmeans/planning'
 import { DEFAULT_ALIAS } from './consts.js'
 import { makeSchemaViews } from './definitions.js'
 import { makeStoreFacade } from './facade.js'
 import { makePluginRegistry } from './registry.js'
-import type { PluginRegistry } from './registry.js'
 import { makeCompositeStore } from './store/composite.js'
 import { makeMemoryPlanningStore } from './store/memory.js'
 import type { BindablePlanningStore } from './store/types.js'
-import type { PlanningHostService, PlanningServiceOptions } from './types.js'
-
-export type PlanningServiceApi = Pick<PlanningService, 'use' | 'plugins' | 'schemas' | 'store' | 'for' | 'committed'>
-
-/** What the facade and the executor reach the service through. */
-export interface PlanningRuntime {
-  service: () => PlanningService
-  registry: PluginRegistry
-  options: PlanningServiceOptions
-  context: () => BasicContext<BasicConfig> | undefined
-  /** The composite store reads and commits go through. */
-  reader: () => PlanningStore
-  /** Every distinct store: the default one first, then each plugin's. */
-  stores: () => PlanningStore[]
-  /** The default store's data-defined schema port, when it has one. */
-  schemaStore: () => SchemaStore | undefined
-  /**
-   * The registry a card of this organization (and project) resolves through. Without a schema
-   * port it is the service's code registry itself — the very same object.
-   */
-  schemasFor: (entityId: string, project?: string) => Promise<PlanningSchemaRegistry>
-  /** The resolved layer. @throws {PlanningUnsupported} without a schema port */
-  scopedSchemas: (entityId: string, project?: string) => Promise<ScopedSchemaRegistry>
-}
+import type { PlanningHostService, PlanningServiceOptions, PlanningRuntime, PlanningServiceApi } from './types.js'
 
 const contextOf = (service: PlanningService): BasicContext<BasicConfig> | undefined =>
   (service as Partial<PlanningHostService>).ctx as BasicContext<BasicConfig> | undefined

package/src/store/commits.ts

@@ -1,9 +1,10 @@
-import { CommitFailed, CommitState, CommitTimeout, DEFAULT_COMMIT_TIMEOUT, WorkcardNotFound } from '@owlmeans/planning'
-import type { CommitEvent, CommitFilter, CommitStatus, Unsubscribe, Workcard } from '@owlmeans/planning'
+import { logger } from '@owlmeans/log'
+import { CommitFailed, CommitState, CommitTimeout, DEFAULT_COMMIT_TIMEOUT, WorkcardNotFound, type CommitEvent, type CommitFilter, type CommitStatus, type Unsubscribe, type Workcard } from '@owlmeans/planning'
 import { COMMIT_POLL_LADDER, DEFAULT_COMMIT_MEMORY } from '../consts.js'
 import type { CommitHub, CommitHubOptions } from './types.js'
+import type { Listener } from './types.local.js'
 
-type Listener = (event: CommitEvent) => void | Promise<void>
+const log = logger('planning:store')
 
 const matches = (event: CommitEvent, filter?: CommitFilter): boolean =>
   filter == null || (
@@ -58,7 +59,7 @@ export const makeCommitHub = (options: CommitHubOptions): CommitHub => {
       const results = await Promise.allSettled(targets.map(async entry => await entry.listener(event)))
       results.forEach(result => {
         if (result.status === 'rejected') {
-          console.error('planning: commit listener failed:', result.reason)
+          log.error('Planning commit listener failed', { transition: event.transition, error: result.reason })
         }
       })
     },

package/src/store/consts.local.ts

@@ -0,0 +1 @@
+export const CONTENT_KEYS = ['body', 'ref', 'format', 'version'] as const

package/src/store/fold.ts

@@ -1,10 +1,9 @@
-import {
-  applyRelationship, applyTransition, CommitState, isProject, PlanningUnsupported, TransitionAction,
-} from '@owlmeans/planning'
-import type {
-  CommitEvent, PlanningStore, Relationship, SpecificationRevision, Transition, Workcard,
-} from '@owlmeans/planning'
+import { logger } from '@owlmeans/log'
+import { applyRelationship, applyTransition, CommitState, isProject, PlanningUnsupported, TransitionAction, type CommitEvent, type PlanningStore, type Relationship, type SpecificationRevision, type Transition, type Workcard } from '@owlmeans/planning'
 import type { FoldOptions, FoldResult } from './types.js'
+import { CONTENT_KEYS } from './consts.local.js'
+
+const log = logger('planning:store')
 
 const isoNow = (): string => new Date().toISOString()
 
@@ -18,7 +17,7 @@ const safely = async (label: string, run: () => Promise<void> | void | undefined
   try {
     await run()
   } catch (error) {
-    console.error(`planning: ${label} failed:`, error)
+    log.error('Planning store step failed', { step: label, error })
   }
 }
 
@@ -161,7 +160,7 @@ export const foldPending = async (
         } catch (advance) {
           // The store itself refuses writes: leave the rest pending for a retry rather than
           // failing every later transition as out of order.
-          console.error(`planning: cannot advance ${cardId} past failed seq ${transition.seq}:`, advance)
+          log.error('Planning cannot advance a card past a failed transition', { cardId, seq: transition.seq, error: advance })
           await safely('commit failure', () => transitions.commit(transition.id!, { state: CommitState.Failed, at, error: message }))
           await safely('publish', () => opts.publish?.(commitEventOf(transition, CommitState.Failed, at, { error: message })))
           return { card, folded, failed, followUp: true }
@@ -210,8 +209,6 @@ export const failPending = async (
   return pending.items.length
 }
 
-const CONTENT_KEYS = ['body', 'ref', 'format', 'version'] as const
-
 /**
  * A specification's history, replayed from its log: one entry per create and per committed
  * content change, newest first. The fold is `applyTransition` itself, so an entry's `body` is the

package/src/store/types.local.ts

@@ -0,0 +1,3 @@
+import type { CommitEvent } from '@owlmeans/planning'
+
+export type Listener = (event: CommitEvent) => void | Promise<void>

package/src/types.local.ts

@@ -0,0 +1,7 @@
+import { PlanningSchemaKind, type StatusFlowSchema, type WorkcardTypeSchema } from '@owlmeans/planning'
+
+export interface Planned {
+  kind: PlanningSchemaKind
+  key: string
+  definition: WorkcardTypeSchema | StatusFlowSchema
+}

package/src/types.ts

@@ -1,11 +1,10 @@
 import type { BasicConfig, BasicContext, LazyService } from '@owlmeans/context'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
-import type {
-  AnyTypeSchema, PlanningPlugin, PlanningScope, PlanningService, PlanningStore, StatusFlowSchema,
-  WithPlanningService,
-} from '@owlmeans/planning'
+import type { AnyTypeSchema, PlanningPlugin, PlanningScope, PlanningService, PlanningStore, StatusFlowSchema, WithPlanningService, PlanningSchemaRegistry, SchemaStore, ScopedSchemaRegistry, CommitEvent, PlanningExecContext, PlanningHookContext, TransitionExecution, WorkcardDraft } from '@owlmeans/planning'
 import type { ApiServerAppend } from '@owlmeans/server-api'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { StoreRoute } from './store/types.js'
+
 
 export interface Config extends ServerConfig { }
 
@@ -96,3 +95,76 @@ export interface PlanningHandlerOptions {
    */
   access?: PlanningAccessResolver
 }
+
+export interface SchemaViewsOptions {
+  /** The code registry every layer starts from. */
+  code: () => PlanningSchemaRegistry
+  /** Bumps whenever the code registry changes (a plugin's `use`). */
+  version: () => number
+  /** The schema port, when the store has one. */
+  port: () => SchemaStore | undefined
+  /** How many resolved layers are kept. */
+  limit?: number
+}
+
+export interface SchemaViews {
+  /** The code registry itself without a port; the resolved layer with one. */
+  of: (entityId: string, project?: string) => Promise<PlanningSchemaRegistry>
+  /** @throws {PlanningUnsupported} without a port */
+  scoped: (entityId: string, project?: string) => Promise<ScopedSchemaRegistry>
+}
+
+export interface ProjectionOptions {
+  /** The planning service alias. */
+  service?: string
+  /** The store the queue folds — the service's default store when omitted. */
+  store?: (service: PlanningService) => PlanningStore
+  /** Where events go — the store's commit hub `publish` when it has one. */
+  publish?: (event: CommitEvent) => Promise<void>
+}
+
+export interface PluginRegistry {
+  /** Register, or replace the plugin of the same `name`. Its schemas are contributed now. */
+  use: (plugin: PlanningPlugin) => void
+  /** Every plugin, `order` ascending (registration order among equals). */
+  plugins: () => PlanningPlugin[]
+  /** The owning plugins that supply a store, in plugin order, each store resolved once. */
+  routes: (ctx?: BasicContext<BasicConfig>) => StoreRoute[]
+  /** The first owning plugin's store for a type, else `fallback`. */
+  storeFor: (type: string | undefined, fallback: PlanningStore, ctx?: BasicContext<BasicConfig>) => PlanningStore
+  /** The first plugin answering a code wins. */
+  mintCode: (
+    draft: WorkcardDraft, taken: (code: string) => Promise<boolean>, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+  ) => Promise<string | undefined>
+  /** The `before` chain; answers the execution the chain left. */
+  before: (
+    exec: TransitionExecution, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+  ) => Promise<TransitionExecution>
+  /** The `after` chain; a failing hook is logged and the chain goes on. */
+  after: (event: CommitEvent, contextOf: (plugin: PlanningPlugin) => PlanningHookContext) => Promise<void>
+  /** Bumps on every `use` — what a cached composite store is keyed by. */
+  version: () => number
+}
+
+export type PlanningServiceApi = Pick<PlanningService, 'use' | 'plugins' | 'schemas' | 'store' | 'for' | 'committed'>
+
+/** What the facade and the executor reach the service through. */
+export interface PlanningRuntime {
+  service: () => PlanningService
+  registry: PluginRegistry
+  options: PlanningServiceOptions
+  context: () => BasicContext<BasicConfig> | undefined
+  /** The composite store reads and commits go through. */
+  reader: () => PlanningStore
+  /** Every distinct store: the default one first, then each plugin's. */
+  stores: () => PlanningStore[]
+  /** The default store's data-defined schema port, when it has one. */
+  schemaStore: () => SchemaStore | undefined
+  /**
+   * The registry a card of this organization (and project) resolves through. Without a schema
+   * port it is the service's code registry itself — the very same object.
+   */
+  schemasFor: (entityId: string, project?: string) => Promise<PlanningSchemaRegistry>
+  /** The resolved layer. @throws {PlanningUnsupported} without a schema port */
+  scopedSchemas: (entityId: string, project?: string) => Promise<ScopedSchemaRegistry>
+}

package/src/utils/index.ts

@@ -1,2 +1,3 @@
 export * from './guard.js'
 export * from './scope.js'
+export type * from './types.js'

package/src/utils/scope.ts

@@ -1,11 +1,11 @@
 import { requireEntityKey } from '@owlmeans/auth-common'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
-import { PLANNING_SERVICE, PlanningForbidden } from '@owlmeans/planning'
-import type { PlanningFacade, PlanningScope, PlanningService, TransitionActor, Workcard } from '@owlmeans/planning'
+import { PLANNING_SERVICE, PlanningForbidden, type PlanningFacade, type PlanningScope, type PlanningService, type TransitionActor, type Workcard } from '@owlmeans/planning'
 import type {
   PlanningAccess, PlanningAccessGrants, PlanningHandlerOptions, PlanningHostService,
 } from '../types.js'
+import type { HandlerScope } from './types.js'
 
 const clean = <T extends object>(record: T): T =>
   Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== '')) as T
@@ -58,12 +58,6 @@ export const planningServiceOf = (
   ctx: BasicContext<BasicConfig>, opts?: Pick<PlanningHandlerOptions, 'service'>
 ): PlanningService => ctx.service<PlanningHostService>(opts?.service ?? PLANNING_SERVICE)
 
-export interface HandlerScope {
-  facade: PlanningFacade
-  /** The resolver's answer, when the handler options carry one. */
-  access?: PlanningAccess
-}
-
 /**
  * The facade a handler works through, and the access it was resolved under.
  *

package/src/utils/types.ts

@@ -0,0 +1,8 @@
+import type { PlanningFacade } from '@owlmeans/planning'
+import type { PlanningAccess } from '../types.js'
+
+export interface HandlerScope {
+  facade: PlanningFacade
+  /** The resolver's answer, when the handler options carry one. */
+  access?: PlanningAccess
+}

package/tests/plugins.spec.ts

@@ -1,3 +1,4 @@
+import { configureLog, logConfig } from '@owlmeans/log'
 import { describe, expect, test } from 'bun:test'
 import { CommitState, PlanningRefused, TransitionAction, WorkcardKind } from '@owlmeans/planning'
 import { makeMemoryPlanningStore } from '../src/store/memory.js'
@@ -66,8 +67,8 @@ describe('@owlmeans/server-planning — plugins', () => {
       ],
     }, { sync: false })
     const planning = facade()
-    const errors = console.error
-    console.error = () => undefined
+    const { level } = logConfig()
+    configureLog({ level: 'silent' })
     try {
       const receipt = await planning.execute({ card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Later' }, action: TransitionAction.Create })
       expect(receipt.transition.commit.state).toBe(CommitState.Pending)
@@ -80,7 +81,7 @@ describe('@owlmeans/server-planning — plugins', () => {
       expect(seen).toEqual([`${receipt.transition.card}:committed:test`])
       expect((await receipt.committed({ timeout: 100 }))!.title).toBe('Later')
     } finally {
-      console.error = errors
+      configureLog({ level })
     }
   })
 })