@owlmeans/planning 0.1.18-rc.8 → 0.1.18

package/src/helpers/status.ts

@@ -1,117 +1,141 @@
 import { ANY_STATUS, INTRINSIC_ORDER, IntrinsicPolicy, IntrinsicStatus } from '../consts.js'
 import { PlanningError, UnknownStatusFlow } from '../errors.js'
-import type {
-  AnyTypeSchema, PlanningSchemaRegistry, StatusDefinition, StatusFlowSchema, StatusTransitionRule,
-} from '../types.js'
+import type { AnyTypeSchema, StatusDefinition, StatusFlowSchema, StatusTransitionRule } from '../types.js'
+import type { StatusHelper } from './status/types.js'
+import type { FlowLookup } from './types.local.js'
+
+export const createStatusHelper = (): StatusHelper => {
+  const primaryFlowOf = (type: AnyTypeSchema): string => {
+    const primary = type.flows[0]
+    if (primary == null) {
+      throw new UnknownStatusFlow(`${type.type}:primary`)
+    }
+
+    return primary
+  }
+
+  const flowIdsOf = (type: AnyTypeSchema): string[] => [...type.flows]
+
+  const statusDefinitionOf = (flow: StatusFlowSchema, status: string): StatusDefinition | undefined =>
+    flow.statuses.find(definition => definition.key === status)
+
+  const intrinsicOf = (flow: StatusFlowSchema, status: string): IntrinsicStatus | undefined =>
+    statusDefinitionOf(flow, status)?.intrinsic
+
+  const initialStatusOf = (flow: StatusFlowSchema): string => {
+    const status = flow.statuses.find(definition => definition.initial === true) ?? flow.statuses[0]
+    if (status == null) {
+      throw new PlanningError(`flow-empty:${flow.id}`)
+    }
+
+    return status.key
+  }
+
+  const isTerminal = (flow: StatusFlowSchema, status: string): boolean =>
+    statusDefinitionOf(flow, status)?.terminal === true
+
+  const fromMatches = (rule: StatusTransitionRule, status: string): boolean =>
+    rule.from === ANY_STATUS || (Array.isArray(rule.from) && rule.from.includes(status))
+
+  const ruleOf = (
+    flow: StatusFlowSchema, transition: string, from: string
+  ): StatusTransitionRule | undefined => {
+    const named = flow.transitions.filter(rule => rule.name === transition)
+
+    return named.find(rule => rule.from !== ANY_STATUS && fromMatches(rule, from))
+      ?? named.find(rule => rule.from === ANY_STATUS)
+      ?? (statusDefinitionOf(flow, from) == null ? named[0] : undefined)
+  }
+
+  const canTransit = (flow: StatusFlowSchema, transition: string, from: string): boolean =>
+    ruleOf(flow, transition, from) != null
+
+  const transitionsFrom = (
+    flow: StatusFlowSchema, status: string, opts?: { explicit?: boolean }
+  ): StatusTransitionRule[] => {
+    const names = [...new Set(flow.transitions.map(rule => rule.name))]
+
+    return names.map(name => ruleOf(flow, name, status))
+      .filter((rule): rule is StatusTransitionRule => rule != null)
+      .filter(rule => opts?.explicit !== true || rule.explicit === true)
+  }
 
-type FlowLookup = Pick<PlanningSchemaRegistry, 'flow'>
+  const initialFlowsOf = (
+    type: AnyTypeSchema, registry: FlowLookup, status?: string
+  ): Record<string, string> => {
+    const primary = primaryFlowOf(type)
 
-/** The primary flow id of a type — `flows[0]`. @throws {UnknownStatusFlow} when it declares none */
-export const primaryFlowOf = (type: AnyTypeSchema): string => {
-  const primary = type.flows[0]
-  if (primary == null) {
-    throw new UnknownStatusFlow(`${type.type}:primary`)
+    return Object.fromEntries(type.flows.map(id => [
+      id, id === primary && status != null ? status : initialStatusOf(registry.flow(id)),
+    ]))
   }
 
-  return primary
+  const resolveIntrinsic = (
+    type: AnyTypeSchema, flows: Record<string, string>, registry: FlowLookup
+  ): IntrinsicStatus => {
+    const read = (id: string): IntrinsicStatus => {
+      const status = flows[id]
+      return status == null
+        ? IntrinsicStatus.Planned
+        : intrinsicOf(registry.flow(id), status) ?? IntrinsicStatus.Planned
+    }
+
+    if (type.intrinsic !== IntrinsicPolicy.All) {
+      return read(primaryFlowOf(type))
+    }
+
+    return type.flows.map(read).reduce<IntrinsicStatus>(
+      (least, intrinsic) => INTRINSIC_ORDER[intrinsic] < INTRINSIC_ORDER[least] ? intrinsic : least,
+      IntrinsicStatus.Closed
+    )
+  }
+
+  return {
+    primaryFlowOf, flowIdsOf, statusDefinitionOf, intrinsicOf, initialStatusOf, isTerminal, ruleOf, canTransit,
+    transitionsFrom, initialFlowsOf, resolveIntrinsic,
+  }
 }
 
-export const flowIdsOf = (type: AnyTypeSchema): string[] => [...type.flows]
+export const statusHelper = createStatusHelper()
+
+/** @deprecated compat:factory-refactor — use `statusHelper.primaryFlowOf(…)` */
+export const primaryFlowOf = (type: AnyTypeSchema): string => statusHelper.primaryFlowOf(type)
 
+/** @deprecated compat:factory-refactor — use `statusHelper.flowIdsOf(…)` */
+export const flowIdsOf = (type: AnyTypeSchema): string[] => statusHelper.flowIdsOf(type)
+
+/** @deprecated compat:factory-refactor — use `statusHelper.statusDefinitionOf(…)` */
 export const statusDefinitionOf = (flow: StatusFlowSchema, status: string): StatusDefinition | undefined =>
-  flow.statuses.find(definition => definition.key === status)
+  statusHelper.statusDefinitionOf(flow, status)
 
-/** The intrinsic state a status maps onto, or `undefined` for a status the flow does not declare. */
+/** @deprecated compat:factory-refactor — use `statusHelper.intrinsicOf(…)` */
 export const intrinsicOf = (flow: StatusFlowSchema, status: string): IntrinsicStatus | undefined =>
-  statusDefinitionOf(flow, status)?.intrinsic
+  statusHelper.intrinsicOf(flow, status)
 
-/** The status marked `initial`, else the first one. @throws {PlanningError} for a flow with none */
-export const initialStatusOf = (flow: StatusFlowSchema): string => {
-  const status = flow.statuses.find(definition => definition.initial === true) ?? flow.statuses[0]
-  if (status == null) {
-    throw new PlanningError(`flow-empty:${flow.id}`)
-  }
+/** @deprecated compat:factory-refactor — use `statusHelper.initialStatusOf(…)` */
+export const initialStatusOf = (flow: StatusFlowSchema): string => statusHelper.initialStatusOf(flow)
 
-  return status.key
-}
+/** @deprecated compat:factory-refactor — use `statusHelper.isTerminal(…)` */
+export const isTerminal = (flow: StatusFlowSchema, status: string): boolean => statusHelper.isTerminal(flow, status)
 
-export const isTerminal = (flow: StatusFlowSchema, status: string): boolean =>
-  statusDefinitionOf(flow, status)?.terminal === true
-
-const fromMatches = (rule: StatusTransitionRule, status: string): boolean =>
-  rule.from === ANY_STATUS || (Array.isArray(rule.from) && rule.from.includes(status))
-
-/**
- * The rule a named transition follows from a status.
- *
- * A name may be declared several times with different `from` sets; the rule naming the status
- * explicitly wins, and a `'*'` rule of that name answers only when none does.
- */
-export const ruleOf = (
-  flow: StatusFlowSchema, transition: string, from: string
-): StatusTransitionRule | undefined => {
-  const named = flow.transitions.filter(rule => rule.name === transition)
-
-  return named.find(rule => rule.from !== ANY_STATUS && fromMatches(rule, from))
-    ?? named.find(rule => rule.from === ANY_STATUS)
-}
+/** @deprecated compat:factory-refactor — use `statusHelper.ruleOf(…)` */
+export const ruleOf = (flow: StatusFlowSchema, transition: string, from: string): StatusTransitionRule | undefined =>
+  statusHelper.ruleOf(flow, transition, from)
 
+/** @deprecated compat:factory-refactor — use `statusHelper.canTransit(…)` */
 export const canTransit = (flow: StatusFlowSchema, transition: string, from: string): boolean =>
-  ruleOf(flow, transition, from) != null
+  statusHelper.canTransit(flow, transition, from)
 
-/**
- * Every transition available from a status, one rule per name (the one `ruleOf` would pick), in
- * declaration order. `explicit: true` keeps only the rules offered to a person.
- */
+/** @deprecated compat:factory-refactor — use `statusHelper.transitionsFrom(…)` */
 export const transitionsFrom = (
   flow: StatusFlowSchema, status: string, opts?: { explicit?: boolean }
-): StatusTransitionRule[] => {
-  const names = [...new Set(flow.transitions.map(rule => rule.name))]
+): StatusTransitionRule[] => statusHelper.transitionsFrom(flow, status, opts)
 
-  return names.map(name => ruleOf(flow, name, status))
-    .filter((rule): rule is StatusTransitionRule => rule != null)
-    .filter(rule => opts?.explicit !== true || rule.explicit === true)
-}
-
-/**
- * A new card's status per flow: every flow's initial status, with the primary one overridden by
- * `status` when the draft names one.
- *
- * @throws {UnknownStatusFlow}
- */
-export const initialFlowsOf = (
-  type: AnyTypeSchema, registry: FlowLookup, status?: string
-): Record<string, string> => {
-  const primary = primaryFlowOf(type)
-
-  return Object.fromEntries(type.flows.map(id => [
-    id, id === primary && status != null ? status : initialStatusOf(registry.flow(id)),
-  ]))
-}
+/** @deprecated compat:factory-refactor — use `statusHelper.initialFlowsOf(…)` */
+export const initialFlowsOf = (type: AnyTypeSchema, registry: FlowLookup, status?: string): Record<string, string> =>
+  statusHelper.initialFlowsOf(type, registry, status)
 
-/**
- * The card's intrinsic state over its flows. {@link IntrinsicPolicy.Primary} reads the primary
- * flow; {@link IntrinsicPolicy.All} takes the least advanced flow. A status the flow does not
- * declare reads as planned.
- *
- * @throws {UnknownStatusFlow}
- */
+/** @deprecated compat:factory-refactor — use `statusHelper.resolveIntrinsic(…)` */
 export const resolveIntrinsic = (
   type: AnyTypeSchema, flows: Record<string, string>, registry: FlowLookup
-): IntrinsicStatus => {
-  const read = (id: string): IntrinsicStatus => {
-    const status = flows[id]
-    return status == null
-      ? IntrinsicStatus.Planned
-      : intrinsicOf(registry.flow(id), status) ?? IntrinsicStatus.Planned
-  }
-
-  if (type.intrinsic !== IntrinsicPolicy.All) {
-    return read(primaryFlowOf(type))
-  }
-
-  return type.flows.map(read).reduce<IntrinsicStatus>(
-    (least, intrinsic) => INTRINSIC_ORDER[intrinsic] < INTRINSIC_ORDER[least] ? intrinsic : least,
-    IntrinsicStatus.Closed
-  )
-}
+): IntrinsicStatus => statusHelper.resolveIntrinsic(type, flows, registry)

package/src/helpers/types.local.ts

@@ -0,0 +1,18 @@
+import type { PlanningSchemaRegistry, PlanningScope } from '../types.js'
+import type { SchemaOrigin } from '../consts.js'
+
+export interface FlowLookup extends Pick<PlanningSchemaRegistry, 'flow'> {}
+
+export interface Scope extends Pick<PlanningScope, 'entityId'> {}
+
+export interface Candidate<T> {
+  origin: SchemaOrigin
+  definition: T
+  retired: boolean
+}
+
+export interface Resolved<T> {
+  definitions: T[]
+  origins: Record<string, SchemaOrigin>
+  retired: string[]
+}

package/src/helpers/validate/types.ts

@@ -0,0 +1,31 @@
+import type { ErrorObject } from 'ajv'
+import type { PlanningSchemaRegistry, SpecificationSlot, Workcard } from '../../types.js'
+
+/** A record's shape, its type's `fields` and a document's body, checked against their schemas. */
+export interface ValidateHelper {
+  assertSchema: (schema: object, value: unknown) => void
+  /** One line per ajv error: `/path message`. */
+  ajvErrorText: (errors?: ErrorObject[] | null) => string
+  /** Keys holding `.` or `$` at any depth — a document store cannot hold them. */
+  invalidFieldKeys: (fields: unknown, path?: string) => string[]
+  /**
+   * Check `fields` against the type's schema, and its keys against the store rule.
+   *
+   * @throws {FieldsInvalid}
+   */
+  validateFields: (registry: Pick<PlanningSchemaRegistry, 'validator'>, type: string, fields: Record<string, unknown>) => void
+  /**
+   * Check a whole record: its shape by kind, then its `fields` by type.
+   *
+   * @throws {PlanningError} `malformed:card:…` for a shape fault
+   * @throws {FieldsInvalid}
+   */
+  validateCard: (card: Workcard, registry: Pick<PlanningSchemaRegistry, 'validator'>) => void
+  /**
+   * Check a document body against its slot: a JSON slot must parse, and match the slot's schema when
+   * it declares one.
+   *
+   * @throws {FieldsInvalid}
+   */
+  validateSpecificationBody: (slot: SpecificationSlot, body?: string | null) => void
+}

package/src/helpers/validate.ts

@@ -1,10 +1,12 @@
 import { Ajv } from 'ajv'
 import type { ErrorObject, ValidateFunction } from 'ajv'
 import formatsPlugin from 'ajv-formats'
+import { memoHelper } from '@owlmeans/context'
 import { SpecificationFormat, WorkcardKind } from '../consts.js'
 import { FieldsInvalid, PlanningError } from '../errors.js'
 import { AnyWorkcardSchema, SpecificationSchema, WorkcardSchema } from '../schemas.js'
 import type { PlanningSchemaRegistry, SpecificationSlot, Workcard } from '../types.js'
+import type { ValidateHelper } from './validate/types.js'
 
 /** The ajv every planning validation compiles with: lenient about unknown keywords, all errors, formats. */
 export const makeAjv = (): Ajv => {
@@ -14,94 +16,104 @@ export const makeAjv = (): Ajv => {
   return ajv
 }
 
-let shared: Ajv | undefined
-const ajvOf = (): Ajv => shared ??= makeAjv()
+export const createValidateHelper = (): ValidateHelper => {
+  const ajvOf = memoHelper.once(makeAjv)
 
-const compiled = new Map<object, ValidateFunction>()
-const compile = (schema: object): ValidateFunction => {
-  let validate = compiled.get(schema)
-  if (validate == null) {
-    validate = ajvOf().compile(schema)
-    compiled.set(schema, validate)
+  const compiled = new Map<object, ValidateFunction>()
+  const compile = (schema: object): ValidateFunction => {
+    let validate = compiled.get(schema)
+    if (validate == null) {
+      validate = ajvOf().compile(schema)
+      compiled.set(schema, validate)
+    }
+
+    return validate
   }
 
-  return validate
-}
+  const ajvErrorText = (errors?: ErrorObject[] | null): string =>
+    (errors ?? []).map(error => `${error.instancePath === '' ? '/' : error.instancePath} ${error.message ?? 'invalid'}`)
+      .join('; ')
 
-/** One line per ajv error: `/path message`. */
-export const ajvErrorText = (errors?: ErrorObject[] | null): string =>
-  (errors ?? []).map(error => `${error.instancePath === '' ? '/' : error.instancePath} ${error.message ?? 'invalid'}`)
-    .join('; ')
+  const invalidFieldKeys = (fields: unknown, path: string = ''): string[] => {
+    if (fields == null || typeof fields !== 'object') {
+      return []
+    }
+    if (Array.isArray(fields)) {
+      return fields.flatMap((entry, index) => invalidFieldKeys(entry, `${path}${index}.`))
+    }
 
-/** Keys holding `.` or `$` at any depth — a document store cannot hold them. */
-export const invalidFieldKeys = (fields: unknown, path: string = ''): string[] => {
-  if (fields == null || typeof fields !== 'object') {
-    return []
-  }
-  if (Array.isArray(fields)) {
-    return fields.flatMap((entry, index) => invalidFieldKeys(entry, `${path}${index}.`))
+    return Object.entries(fields).flatMap(([key, value]) => [
+      ...(key.includes('.') || key.includes('$') ? [`${path}${key}`] : []),
+      ...invalidFieldKeys(value, `${path}${key}.`),
+    ])
   }
 
-  return Object.entries(fields).flatMap(([key, value]) => [
-    ...(key.includes('.') || key.includes('$') ? [`${path}${key}`] : []),
-    ...invalidFieldKeys(value, `${path}${key}.`),
-  ])
-}
-
-/**
- * Check `fields` against the type's schema, and its keys against the store rule.
- *
- * @throws {FieldsInvalid}
- */
-export const validateFields = (
-  registry: Pick<PlanningSchemaRegistry, 'validator'>, type: string, fields: Record<string, unknown>
-): void => {
-  const keys = invalidFieldKeys(fields)
-  if (keys.length > 0) {
-    throw new FieldsInvalid(`keys:${keys.join(',')}`)
-  }
-  const validate = registry.validator(type)
-  if (!validate(fields)) {
-    throw new FieldsInvalid(`${type}:${ajvErrorText(validate.errors)}`)
+  const validateFields = (
+    registry: Pick<PlanningSchemaRegistry, 'validator'>, type: string, fields: Record<string, unknown>
+  ): void => {
+    const keys = invalidFieldKeys(fields)
+    if (keys.length > 0) {
+      throw new FieldsInvalid(`keys:${keys.join(',')}`)
+    }
+    const validate = registry.validator(type)
+    if (!validate(fields)) {
+      throw new FieldsInvalid(`${type}:${ajvErrorText(validate.errors)}`)
+    }
   }
-}
 
-/**
- * Check a whole record: its shape by kind, then its `fields` by type.
- *
- * @throws {PlanningError} `malformed:card:…` for a shape fault
- * @throws {FieldsInvalid}
- */
-export const validateCard = (card: Workcard, registry: Pick<PlanningSchemaRegistry, 'validator'>): void => {
-  const validate = compile(card.kind === WorkcardKind.Specification
-    ? SpecificationSchema
-    : card.kind === WorkcardKind.Card || card.kind === WorkcardKind.Project ? WorkcardSchema : AnyWorkcardSchema)
-  if (!validate(card)) {
-    throw new PlanningError(`malformed:card:${ajvErrorText(validate.errors)}`)
+  const validateCard = (card: Workcard, registry: Pick<PlanningSchemaRegistry, 'validator'>): void => {
+    const validate = compile(card.kind === WorkcardKind.Specification
+      ? SpecificationSchema
+      : card.kind === WorkcardKind.Card || card.kind === WorkcardKind.Project ? WorkcardSchema : AnyWorkcardSchema)
+    if (!validate(card)) {
+      throw new PlanningError(`malformed:card:${ajvErrorText(validate.errors)}`)
+    }
+    validateFields(registry, card.type, card.fields)
   }
-  validateFields(registry, card.type, card.fields)
-}
 
-/**
- * Check a document body against its slot: a JSON slot must parse, and match the slot's schema when
- * it declares one.
- *
- * @throws {FieldsInvalid}
- */
-export const validateSpecificationBody = (slot: SpecificationSlot, body?: string | null): void => {
-  if (body == null || slot.format !== SpecificationFormat.Json) {
-    return
-  }
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(body)
-  } catch {
-    throw new FieldsInvalid(`body:${slot.category}:not-json`)
-  }
-  if (slot.schema != null && typeof slot.schema === 'object') {
-    const validate = compile(slot.schema)
-    if (!validate(parsed)) {
-      throw new FieldsInvalid(`body:${slot.category}:${ajvErrorText(validate.errors)}`)
+  const validateSpecificationBody = (slot: SpecificationSlot, body?: string | null): void => {
+    if (body == null || slot.format !== SpecificationFormat.Json) {
+      return
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(body)
+    } catch {
+      throw new FieldsInvalid(`body:${slot.category}:not-json`)
+    }
+    if (slot.schema != null && typeof slot.schema === 'object') {
+      const validate = compile(slot.schema)
+      if (!validate(parsed)) {
+        throw new FieldsInvalid(`body:${slot.category}:${ajvErrorText(validate.errors)}`)
+      }
     }
   }
+
+  const assertSchema = (schema: object, value: unknown): void => {
+    const validate = compile(schema)
+    if (!validate(value)) throw new FieldsInvalid(ajvErrorText(validate.errors))
+  }
+
+  return { assertSchema, ajvErrorText, invalidFieldKeys, validateFields, validateCard, validateSpecificationBody }
 }
+
+export const validateHelper = createValidateHelper()
+
+/** @deprecated compat:factory-refactor — use `validateHelper.ajvErrorText(…)` */
+export const ajvErrorText = (errors?: ErrorObject[] | null): string => validateHelper.ajvErrorText(errors)
+
+/** @deprecated compat:factory-refactor — use `validateHelper.invalidFieldKeys(…)` */
+export const invalidFieldKeys = (fields: unknown, path: string = ''): string[] => validateHelper.invalidFieldKeys(fields, path)
+
+/** @deprecated compat:factory-refactor — use `validateHelper.validateFields(…)` */
+export const validateFields = (
+  registry: Pick<PlanningSchemaRegistry, 'validator'>, type: string, fields: Record<string, unknown>
+): void => validateHelper.validateFields(registry, type, fields)
+
+/** @deprecated compat:factory-refactor — use `validateHelper.validateCard(…)` */
+export const validateCard = (card: Workcard, registry: Pick<PlanningSchemaRegistry, 'validator'>): void =>
+  validateHelper.validateCard(card, registry)
+
+/** @deprecated compat:factory-refactor — use `validateHelper.validateSpecificationBody(…)` */
+export const validateSpecificationBody = (slot: SpecificationSlot, body?: string | null): void =>
+  validateHelper.validateSpecificationBody(slot, body)

package/src/helpers/wire/types.ts

@@ -0,0 +1,31 @@
+import type { Sort } from '@owlmeans/resource'
+import type {
+  RelationshipQuery, RelationshipQueryWire, SpecificationQuery, SpecificationQueryWire, SummaryQuery, SummaryQueryWire,
+  TransitionQuery, TransitionQueryWire, WorkcardQuery, WorkcardQueryWire,
+} from '../../types.js'
+
+/**
+ * The query objects to and from the shape they travel in a URL (`*QueryWire`): a list is
+ * comma-joined (JSON when an element holds a comma), an object is JSON, a sort is `field,-field`.
+ * Every decoder also accepts the rich form.
+ */
+export interface WireHelper {
+  /** A list as one query value: comma-joined, or JSON when an element itself holds a comma. */
+  encodeList: (value?: string | readonly string[] | null) => string | undefined
+  /** Every entry of a list query value, whatever shape the transport left it in. */
+  decodeList: (value: unknown, key?: string) => string[] | undefined
+  /** `[{ field: 'order' }, { field: 'updatedAt', order: 'desc' }]` ⇄ `order,-updatedAt`. */
+  encodeSort: <T>(sort?: Sort<T>[] | null) => string | undefined
+  decodeSort: <T>(value: unknown) => Sort<T>[] | undefined
+  encodeWorkcardQuery: (query?: WorkcardQuery | null) => WorkcardQueryWire
+  /** @throws {PlanningError} `malformed:query:<key>` for a value that does not decode */
+  decodeWorkcardQuery: (wire?: WorkcardQueryWire | WorkcardQuery | null) => WorkcardQuery
+  encodeSummaryQuery: (query: SummaryQuery) => SummaryQueryWire
+  decodeSummaryQuery: (wire?: SummaryQueryWire | SummaryQuery | null) => SummaryQuery
+  encodeTransitionQuery: (query?: TransitionQuery | null) => TransitionQueryWire
+  decodeTransitionQuery: (wire?: TransitionQueryWire | TransitionQuery | null) => TransitionQuery
+  encodeSpecificationQuery: (query?: SpecificationQuery | null) => SpecificationQueryWire
+  decodeSpecificationQuery: (wire?: SpecificationQueryWire | SpecificationQuery | null) => SpecificationQuery
+  encodeRelationshipQuery: (query?: RelationshipQuery | null) => RelationshipQueryWire
+  decodeRelationshipQuery: (wire?: RelationshipQueryWire | RelationshipQuery | null) => RelationshipQuery
+}