@owlmeans/client-planning 0.1.18-rc.9 → 0.1.18

package/src/sync/types.ts

@@ -0,0 +1,18 @@
+import type { Relationship, Workcard } from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import type { PlanningStores, SyncOptions } from '../types.js'
+
+/** An authoritative list made true in one mirror store — within a scope, never beyond it. */
+export interface SyncHelper {
+  /**
+   * Make the store agree with an authoritative list WITHIN a scope: every card given is written
+   * (unless the store holds a newer fold of it), and every card matching `where` that the list does
+   * not name is dropped. Cards outside `where` are left alone — which is why this, and never
+   * `replace()`, is how a list reaches the one shared card store.
+   *
+   * Unchanged cards are not rewritten, so a periodic re-seed wakes no subscriber.
+   */
+  syncCards: (store: PlanningStores['cards'], items: Workcard[], where?: Criteria<Workcard>, opts?: SyncOptions) => Promise<void>
+  /** {@link SyncHelper.syncCards} for the link store. */
+  syncLinks: (store: PlanningStores['links'], items: Relationship[], where?: Criteria<Relationship>, opts?: SyncOptions) => Promise<void>
+}

package/src/sync.ts

@@ -0,0 +1,40 @@
+import type { Relationship, Workcard } from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import type { SyncHelper } from './sync/types.js'
+import type { PlanningStores, SyncOptions } from './types.js'
+import { recordUtils } from './utils/record.js'
+
+export const createSyncHelper = (): SyncHelper => {
+  const syncCards = async (
+    store: PlanningStores['cards'], items: Workcard[], where?: Criteria<Workcard>, opts?: SyncOptions
+  ): Promise<void> => {
+    await dropUnnamed(store, recordUtils.idsOf(items), where, opts)
+    for (const item of items) {
+      await recordUtils.putCard(store, item)
+    }
+  }
+
+  const syncLinks = async (
+    store: PlanningStores['links'], items: Relationship[], where?: Criteria<Relationship>, opts?: SyncOptions
+  ): Promise<void> => {
+    await dropUnnamed(store, recordUtils.idsOf(items), where, opts)
+    for (const item of items) {
+      await recordUtils.putLink(store, item)
+    }
+  }
+
+  const dropUnnamed = async <T extends Workcard | Relationship>(
+    store: PlanningStores['cards'] | PlanningStores['links'], named: string[], where?: Criteria<T>, opts?: SyncOptions
+  ): Promise<void> => {
+    const keep = new Set([...named, ...(opts?.keep ?? [])])
+    const scoped = await (store as PlanningStores['cards']).list(where as Criteria<Workcard>)
+    const stale = recordUtils.idsOf(scoped.items).filter(id => !keep.has(id))
+    if (stale.length > 0) {
+      await store.purge({ id: { $in: stale } })
+    }
+  }
+
+  return { syncCards, syncLinks }
+}
+
+export const syncHelper = createSyncHelper()

package/src/types.local.ts

@@ -0,0 +1,14 @@
+import type { CommitEvent, CommitFilter } from '@owlmeans/planning'
+import type { Connection } from '@owlmeans/socket'
+import type { PlanningOperation } from './lifecycle/types.js'
+
+export interface Subscription {
+  operation: PlanningOperation
+  listener: (event: CommitEvent) => void | Promise<void>
+  filter?: CommitFilter
+}
+
+export interface CommitSocketOpening {
+  operation: PlanningOperation
+  promise: Promise<Connection | null>
+}

package/src/types.ts

@@ -2,13 +2,14 @@ import type { ClientConfig, ClientContext } from '@owlmeans/client-context'
 import type { LazyService } from '@owlmeans/context'
 import type { AbstractRequest, EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
 import type {
-  CommitFilter, CommitSource, CommitState, PlanningFacade, PlanningProtocols, PlanningSchemaRegistry,
-  PlanningScope, PlanningService, Relationship, RelationshipQuery, TransitionAction, Workcard,
-  WorkcardKind, WorkcardQuery,
+  CommitFilter, CommitSource, CommitState, PlanningDefinitions, PlanningFacade, PlanningProtocols,
+  PlanningSchemaRegistry, PlanningScope, PlanningService, Relationship, RelationshipQuery, TransitionAction,
+  Workcard, WorkcardKind, WorkcardQuery,
 } from '@owlmeans/planning'
 import type { Criteria, ResourceRecord } from '@owlmeans/resource'
 import type { Connection } from '@owlmeans/socket'
 import type { StateAlias, StateResource } from '@owlmeans/state'
+import type { PlanningClientLifecycle } from './lifecycle/types.js'
 
 export interface Config extends ClientConfig { }
 
@@ -24,6 +25,8 @@ export interface PlanningSocketOpener {
 }
 
 export interface PlanningClientOptions {
+  /** Current organization slug and authenticated session identity; never an organization record id on the wire. */
+  scopeKey?: () => string | undefined
   /** The tree the server mounted — the same `makePlanningProtocols` call, alias for alias. */
   protocols: PlanningProtocols
   /**
@@ -49,13 +52,34 @@ export interface PlanningClientOptions {
 
 /** What `appendPlanningClient` registers under `PLANNING_SERVICE`. */
 export interface PlanningClientService extends PlanningService, LazyService {
+  /** Shared by stock facades and feeds; local mutations never cross its close boundary. */
+  lifecycle: PlanningClientLifecycle
+  scopeKey: () => string
+  registerFeed: (feed: PlanningFeed) => import('@owlmeans/planning').Unsubscribe
   /** A facade over the remote tree. The scope is advisory (see {@link PlanningClientOptions.scope}). */
   for: (scope?: Partial<PlanningScope>) => PlanningFacade
   commits: RemoteCommitSource
   /** The registry, loaded from the server's bundle — once, unless `force`d. */
   loadSchemas: (opts?: { force?: boolean }) => Promise<PlanningSchemaRegistry>
-  /** Release the shared commit socket. */
+  /** Cancel old requests and feeds, drain local mutations, close the socket and clear mirrors. */
   close: () => Promise<void>
+  /** Data-defined types and flows — present when the tree was declared with `definitions: true`. */
+  definitions?: RemoteDefinitions
+}
+
+/** The client half of `PlanningDefinitions`: layers cached per project, dropped on any write. */
+export interface RemoteDefinitions extends PlanningDefinitions {
+  /** Forget every cached layer — the next read asks the server. */
+  invalidate: () => void
+}
+
+export interface RemoteDefinitionsOptions {
+  lifecycle?: PlanningClientLifecycle
+  scopeKey?: () => string
+  /** Milliseconds, for every definitions call. */
+  timeout?: number
+  /** Called after every write (the service reloads its own bundle on the next `model()`). */
+  onWrite?: () => void
 }
 
 export interface WithPlanningClient {
@@ -65,11 +89,13 @@ export interface WithPlanningClient {
 export interface RemoteCommitSource extends CommitSource {
   /** A socket is open under this source. */
   connected: () => boolean
-  /** Release the shared socket. Subscriptions stop receiving until the next `subscribe`. */
+  /** Cancel waits and subscriptions and release the socket, including a late-opening carrier. */
   close: () => Promise<void>
 }
 
 export interface RemoteCommitSourceOptions {
+  lifecycle?: PlanningClientLifecycle
+  scopeKey?: () => string
   socket?: PlanningSocketOpener
   /** Seconds. */
   poll?: number
@@ -80,12 +106,16 @@ export interface RemoteCommitSourceOptions {
 }
 
 export interface RemoteFacadeOptions {
+  lifecycle?: PlanningClientLifecycle
+  scopeKey?: () => string
   commits: RemoteCommitSource
   schemas: PlanningSchemaRegistry
   /** Resolves the registry before a model is built. */
   loadSchemas?: () => Promise<PlanningSchemaRegistry>
   timeout?: number
   stores?: () => PlanningStores | null
+  /** The data-defined schema surface, shared by every facade of the service. */
+  definitions?: RemoteDefinitions
 }
 
 /** One row per transition the client wrote or saw settle. */
@@ -105,12 +135,20 @@ export interface PlanningCommitRecord extends ResourceRecord {
 }
 
 export interface PlanningStoreAliases {
+  mentions: StateAlias<import('@owlmeans/planning').CommentMention>
+  comments: StateAlias<import('@owlmeans/planning').Comment>
+  teams: StateAlias<import('@owlmeans/planning').Team>
+  assignees: StateAlias<import('@owlmeans/planning').Assignee>
   cards: StateAlias<Workcard>
   links: StateAlias<Relationship>
   commits: StateAlias<PlanningCommitRecord>
 }
 
 export interface PlanningStores {
+  mentions: StateResource<import('@owlmeans/planning').CommentMention>
+  comments: StateResource<import('@owlmeans/planning').Comment>
+  teams: StateResource<import('@owlmeans/planning').Team>
+  assignees: StateResource<import('@owlmeans/planning').Assignee>
   cards: StateResource<Workcard>
   links: StateResource<Relationship>
   commits: StateResource<PlanningCommitRecord>
@@ -161,3 +199,13 @@ export interface PlanningFeed extends Readonly<PlanningFeedState> {
   /** Stop folding frames and refreshing. The shared socket stays open. */
   stop: () => Promise<void>
 }
+
+export interface PlanningResourceFeedOptions {
+  assignees?: import('@owlmeans/planning').AssigneeQuery
+  teams?: import('@owlmeans/planning').TeamQuery
+  comments?: import('@owlmeans/planning').CommentQuery
+  mentions?: import('@owlmeans/planning').MentionQuery
+  refresh?: number
+  scope?: Partial<PlanningScope>
+  onChange?: (state: PlanningFeedState) => void
+}

package/src/utils/record/types.ts

@@ -0,0 +1,27 @@
+import type { CommitState, Relationship, Workcard } from '@owlmeans/planning'
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { StateResource } from '@owlmeans/state'
+import type { PlanningCommitRecord, PlanningStores } from '../../types.js'
+
+/** How a record is written into the state mirror: only when it is newer, and only when it changed. */
+export interface RecordUtils {
+  /** Same content, whatever order the keys arrived in. */
+  sameRecord: (left: unknown, right: unknown) => boolean
+  /**
+   * Write one card unless the store already holds a NEWER fold of it.
+   *
+   * `seq` is the last folded transition, so a lower one is an older picture — a list fetched before a
+   * commit landed must not undo that commit. The head only ever grows: a head this client allocated
+   * (`applyReceipt`) stays until a fold catches up with it.
+   */
+  putCard: (store: StateResource<Workcard>, card: Workcard) => Promise<Workcard>
+  putLink: (store: StateResource<Relationship>, link: Relationship) => Promise<void>
+  /** Drop a card, whatever lives under it when it is a project, and every link touching any of them. */
+  dropCard: (stores: PlanningStores, id: string, project: boolean) => Promise<void>
+  /** Record what is known about a transition, merged over what was known before. */
+  putCommit: (
+    store: StateResource<PlanningCommitRecord>, record: Partial<PlanningCommitRecord> & { id: string, state: CommitState }
+  ) => Promise<PlanningCommitRecord>
+  clean: <T extends object>(record: T) => T
+  idsOf: <T extends ResourceRecord>(records: T[]) => string[]
+}

package/src/utils/record.ts

@@ -2,90 +2,87 @@ import type { PlanningCommitRecord, PlanningStores } from '../types.js'
 import type { CommitState, Relationship, Workcard } from '@owlmeans/planning'
 import type { ResourceRecord } from '@owlmeans/resource'
 import type { StateResource } from '@owlmeans/state'
+import type { RecordUtils } from './record/types.js'
 
-const stable = (value: unknown): unknown => {
-  if (Array.isArray(value)) {
-    return value.map(stable)
-  }
-  if (value != null && typeof value === 'object') {
-    return Object.fromEntries(Object.entries(value as Record<string, unknown>)
-      .filter(([, entry]) => entry !== undefined)
-      .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
-      .map(([key, entry]) => [key, stable(entry)]))
+export const createRecordUtils = (): RecordUtils => {
+  const stable = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+      return value.map(stable)
+    }
+    if (value != null && typeof value === 'object') {
+      return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([key, entry]) => [key, stable(entry)]))
+    }
+
+    return value
   }
 
-  return value
-}
+  const sameRecord = (left: unknown, right: unknown): boolean =>
+    JSON.stringify(stable(left)) === JSON.stringify(stable(right))
 
-/** Same content, whatever order the keys arrived in. */
-export const sameRecord = (left: unknown, right: unknown): boolean =>
-  JSON.stringify(stable(left)) === JSON.stringify(stable(right))
+  const putCard = async (store: StateResource<Workcard>, card: Workcard): Promise<Workcard> => {
+    if (card.id == null) {
+      return card
+    }
+    const known = await store.load(card.id)
+    if (known != null && (known.seq ?? 0) > (card.seq ?? 0)) {
+      return known
+    }
+    const head = Math.max(card.head ?? card.seq ?? 0, known?.head ?? 0)
+    const next = head > (card.head ?? card.seq ?? 0) ? { ...card, head } : card
+    if (known != null && sameRecord(known, next)) {
+      return known
+    }
+    await store.save(next)
 
-/**
- * Write one card unless the store already holds a NEWER fold of it.
- *
- * `seq` is the last folded transition, so a lower one is an older picture — a list fetched before a
- * commit landed must not undo that commit. The head only ever grows: a head this client allocated
- * (`applyReceipt`) stays until a fold catches up with it.
- */
-export const putCard = async (store: StateResource<Workcard>, card: Workcard): Promise<Workcard> => {
-  if (card.id == null) {
-    return card
+    return next
   }
-  const known = await store.load(card.id)
-  if (known != null && (known.seq ?? 0) > (card.seq ?? 0)) {
-    return known
+
+  const putLink = async (store: StateResource<Relationship>, link: Relationship): Promise<void> => {
+    if (link.id == null) {
+      return
+    }
+    const known = await store.load(link.id)
+    if (known != null && sameRecord(known, link)) {
+      return
+    }
+    await store.save(link)
   }
-  const head = Math.max(card.head ?? card.seq ?? 0, known?.head ?? 0)
-  const next = head > (card.head ?? card.seq ?? 0) ? { ...card, head } : card
-  if (known != null && sameRecord(known, next)) {
-    return known
+
+  const dropCard = async (stores: PlanningStores, id: string, project: boolean): Promise<void> => {
+    const ids = [id]
+    if (project) {
+      const children = await stores.cards.list({ parents: { $contains: [id] } })
+      ids.push(...children.items.map(child => child.id).filter((child): child is string => child != null))
+    }
+    await stores.cards.purge({ id: { $in: ids } })
+    if (await stores.links.count({ $or: [{ from: { $in: ids } }, { to: { $in: ids } }] }) > 0) {
+      await stores.links.purge({ $or: [{ from: { $in: ids } }, { to: { $in: ids } }] })
+    }
   }
-  await store.save(next)
 
-  return next
-}
+  const putCommit = async (
+    store: StateResource<PlanningCommitRecord>, record: Partial<PlanningCommitRecord> & { id: string, state: CommitState }
+  ): Promise<PlanningCommitRecord> => {
+    const known = await store.load(record.id)
+    const next = { ...known, ...clean(record) } as PlanningCommitRecord
+    if (known != null && sameRecord(known, next)) {
+      return known
+    }
+    await store.save(next)
 
-export const putLink = async (store: StateResource<Relationship>, link: Relationship): Promise<void> => {
-  if (link.id == null) {
-    return
-  }
-  const known = await store.load(link.id)
-  if (known != null && sameRecord(known, link)) {
-    return
+    return next
   }
-  await store.save(link)
-}
 
-/** Drop a card, whatever lives under it when it is a project, and every link touching any of them. */
-export const dropCard = async (stores: PlanningStores, id: string, project: boolean): Promise<void> => {
-  const ids = [id]
-  if (project) {
-    const children = await stores.cards.list({ parents: { $contains: [id] } })
-    ids.push(...children.items.map(child => child.id).filter((child): child is string => child != null))
-  }
-  await stores.cards.purge({ id: { $in: ids } })
-  if (await stores.links.count({ $or: [{ from: { $in: ids } }, { to: { $in: ids } }] }) > 0) {
-    await stores.links.purge({ $or: [{ from: { $in: ids } }, { to: { $in: ids } }] })
-  }
-}
+  const clean = <T extends object>(record: T): T =>
+    Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
 
-/** Record what is known about a transition, merged over what was known before. */
-export const putCommit = async (
-  store: StateResource<PlanningCommitRecord>, record: Partial<PlanningCommitRecord> & { id: string, state: CommitState }
-): Promise<PlanningCommitRecord> => {
-  const known = await store.load(record.id)
-  const next = { ...known, ...clean(record) } as PlanningCommitRecord
-  if (known != null && sameRecord(known, next)) {
-    return known
-  }
-  await store.save(next)
+  const idsOf = <T extends ResourceRecord>(records: T[]): string[] =>
+    records.map(record => record.id).filter((id): id is string => id != null)
 
-  return next
+  return { sameRecord, putCard, putLink, dropCard, putCommit, clean, idsOf }
 }
 
-export const clean = <T extends object>(record: T): T =>
-  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
-
-export const idsOf = <T extends ResourceRecord>(records: T[]): string[] =>
-  records.map(record => record.id).filter((id): id is string => id != null)
+export const recordUtils = createRecordUtils()