@pathmx/core 0.5.0

package/view/model.ts

@@ -0,0 +1,91 @@
+import type { ActionAffordance } from "../actions/actions.ts"
+import type { Actor, Principal, UserActor } from "../authority/model.ts"
+import type { ViewQuery } from "../query/model.ts"
+import type { BlockType, SourceType } from "../schema/model.ts"
+import type { MarkdownList, MarkdownTask } from "../source/index.ts"
+
+export type ViewIdentity =
+  | Readonly<{ type: "anonymous" }>
+  | Readonly<{ type: "authenticated"; subject: UserActor }>
+  | Readonly<{ type: "inspection"; subject: Actor }>
+
+type SourceViewMeta = Readonly<{
+  title: string
+  description?: string
+  image?: string
+}>
+
+type BlockViewMeta = Readonly<{
+  title?: string
+  description?: string
+  image?: string
+}>
+
+export type SourceView = Readonly<{
+  id: string
+  type: string
+  href: string
+  sourceType: SourceType
+  qualifiers: readonly string[]
+  data: Readonly<Record<string, unknown>>
+  body: string
+  blocks: readonly BlockView[]
+  meta: SourceViewMeta
+}>
+
+export type BlockView = Readonly<{
+  id: string
+  type: string
+  href: string
+  blockType: BlockType
+  data: Readonly<Record<string, unknown>>
+  body: string
+  lists: readonly MarkdownList[]
+  tasks: readonly MarkdownTask[]
+  meta: BlockViewMeta
+}>
+
+export type SourceSummary = Readonly<{
+  id: string
+  type: string
+  href: string
+  sourceType: SourceType
+  qualifiers: readonly string[]
+  data: Readonly<Record<string, unknown>>
+  meta: SourceView["meta"]
+}>
+
+export type BlockSummary = BlockView &
+  Readonly<{
+    source: SourceSummary
+  }>
+
+export type SourceRelation = Readonly<{
+  rel: string
+  qualifiers: readonly string[]
+  type:
+    | "source"
+    | "asset"
+    | "external"
+    | "fragment"
+    | "actor-relative"
+    | "unresolved"
+  label?: string
+  target?: Readonly<{ type: "source"; id: string }>
+  href: string
+  fragment?: string
+}>
+
+export type SourceDescription = Readonly<{
+  source: SourceView
+  relations: readonly SourceRelation[]
+  actions: readonly ActionAffordance[]
+}>
+
+export type View = Readonly<{
+  identity: ViewIdentity
+  principal: Principal
+  query: ViewQuery
+  readSource(id: string): SourceView | undefined
+  describeSource(id: string): Promise<SourceDescription | undefined>
+}>

package/view/projection.ts

@@ -0,0 +1,162 @@
+import { publicPath } from "../server/router.ts"
+import {
+  deriveBlockMeta,
+  deriveSourceMeta,
+  type Source,
+  type SourceBlock,
+} from "../source/index.ts"
+import type { ApplicationSchema, SourceType } from "../schema/model.ts"
+import type {
+  BlockSummary,
+  BlockView,
+  SourceSummary,
+  SourceView,
+} from "./model.ts"
+
+const sourceViews = new WeakMap<Source, WeakMap<SourceType, SourceView>>()
+const sourceSummaries = new WeakMap<
+  Source,
+  WeakMap<SourceType, SourceSummary>
+>()
+
+function immutableValue(
+  value: unknown,
+  seen = new WeakMap<object, unknown>(),
+): unknown {
+  if (Array.isArray(value)) {
+    const existing = seen.get(value)
+    if (existing) return existing
+    const projected: unknown[] = []
+    seen.set(value, projected)
+    for (const item of value) projected.push(immutableValue(item, seen))
+    return Object.freeze(projected)
+  }
+  if (value == null || typeof value !== "object") return value
+
+  const existing = seen.get(value)
+  if (existing) return existing
+  const projected = Object.create(null) as Record<string, unknown>
+  seen.set(value, projected)
+  for (const [key, item] of Object.entries(value)) {
+    projected[key] = immutableValue(item, seen)
+  }
+  return Object.freeze(projected)
+}
+
+function projectionCache<T>(
+  cache: WeakMap<Source, WeakMap<SourceType, T>>,
+  source: Source,
+) {
+  let projections = cache.get(source)
+  if (!projections) {
+    projections = new WeakMap()
+    cache.set(source, projections)
+  }
+  return projections
+}
+
+function projectMeta(derived: {
+  title: string
+  description: string
+  image: string
+}): SourceView["meta"] {
+  return Object.freeze({
+    title: derived.title,
+    ...(derived.description ? { description: derived.description } : {}),
+    ...(derived.image ? { image: derived.image } : {}),
+  })
+}
+
+function projectBlockMeta(derived: {
+  title: string
+  description: string
+  image: string
+}): BlockView["meta"] {
+  return Object.freeze({
+    ...(derived.title ? { title: derived.title } : {}),
+    ...(derived.description ? { description: derived.description } : {}),
+    ...(derived.image ? { image: derived.image } : {}),
+  })
+}
+
+function projectBlock(
+  source: Source,
+  block: SourceBlock,
+  schema: ApplicationSchema,
+): BlockView {
+  let meta: BlockView["meta"] | undefined
+  return Object.freeze({
+    id: block.id,
+    type: block.type,
+    href: `${publicPath(source)}#${encodeURIComponent(block.id)}`,
+    blockType: schema.blockType(block),
+    data: immutableValue(block.data) as Readonly<Record<string, unknown>>,
+    body: block.body,
+    /** Preserve lazy indexing while exposing only immutable list data. */
+    get lists() {
+      return block.lists
+    },
+    /** Tasks and lists share the canonical Block's lazy structural parse. */
+    get tasks() {
+      return block.tasks
+    },
+    /** Derive Block metadata only for consumers that request it. */
+    get meta() {
+      return (meta ??= projectBlockMeta(deriveBlockMeta(block, source)))
+    },
+  })
+}
+
+/** @internal Project one canonical Source for query and View consumers. */
+export function projectSourceSummary(
+  source: Source,
+  schema: ApplicationSchema,
+) {
+  const sourceType = schema.sourceType(source)
+  const cache = projectionCache(sourceSummaries, source)
+  const cached = cache.get(sourceType)
+  if (cached) return cached
+  const summary: SourceSummary = Object.freeze({
+    id: source.id,
+    type: source.type,
+    href: publicPath(source),
+    sourceType,
+    qualifiers: Object.freeze([...source.qualifiers]),
+    data: immutableValue(source.data) as Readonly<Record<string, unknown>>,
+    meta: projectMeta(deriveSourceMeta(source)),
+  })
+  cache.set(sourceType, summary)
+  return summary
+}
+
+/** @internal Project one canonical Block with its containing Source context. */
+export function projectBlockSummary(
+  source: Source,
+  block: SourceBlock,
+  schema: ApplicationSchema,
+): BlockSummary {
+  return Object.freeze({
+    ...projectBlock(source, block, schema),
+    source: projectSourceSummary(source, schema),
+  })
+}
+
+/** @internal Project one complete canonical Source for a View. */
+export function projectSource(source: Source, schema: ApplicationSchema) {
+  const sourceType = schema.sourceType(source)
+  const cache = projectionCache(sourceViews, source)
+  const cached = cache.get(sourceType)
+  if (cached) return cached
+
+  const summary = projectSourceSummary(source, schema)
+  const projected: SourceView = Object.freeze({
+    ...summary,
+    data: immutableValue(source.data) as Readonly<Record<string, unknown>>,
+    body: source.body,
+    blocks: Object.freeze(
+      source.blocks.map((block) => projectBlock(source, block, schema)),
+    ),
+  })
+  cache.set(sourceType, projected)
+  return projected
+}

package/view/session.ts

@@ -0,0 +1,146 @@
+import type { Engine } from "../host/engine.ts"
+import { canonicalPath } from "../canonical.ts"
+import type { Source } from "../source/index.ts"
+import type { Actor, CredentialSession, Principal } from "../authority/model.ts"
+import { principalFor } from "../authority/model.ts"
+import type { View, ViewIdentity } from "./model.ts"
+import type { ViewQuery } from "../query/model.ts"
+import { projectSource } from "./projection.ts"
+
+function identityFor(session: CredentialSession): ViewIdentity {
+  return session.type === "authenticated"
+    ? Object.freeze({ type: "authenticated", subject: session.actor })
+    : Object.freeze({ type: "anonymous" })
+}
+
+function within(id: string, root: string) {
+  return root === "/" || id === root || id.startsWith(`${root}/`)
+}
+
+function actorRelativeSource(
+  engine: Engine,
+  principal: Principal,
+  href: string,
+) {
+  if (principal.type !== "actor" || !href.startsWith("~/")) return
+  const pathname = href.slice(2).split(/[?#]/, 1)[0]
+  if (!pathname) return
+  const candidate = engine.environment.path.join(principal.actor.home, pathname)
+  try {
+    canonicalPath(candidate)
+  } catch {
+    return
+  }
+  if (!within(candidate, principal.actor.home)) return
+  return (
+    engine.repo.get(candidate) ??
+    engine.repo.atPath(candidate) ??
+    engine.resolve(candidate)
+  )
+}
+
+class EngineView implements View {
+  readonly #engine: Engine
+  readonly identity: ViewIdentity
+  readonly principal: Principal
+  readonly query: ViewQuery
+
+  constructor(engine: Engine, identity: ViewIdentity, principal: Principal) {
+    this.#engine = engine
+    this.identity = identity
+    this.principal = principal
+    this.query = engine.queries.viewQuery(this)
+    Object.freeze(this)
+  }
+
+  readSource(id: string) {
+    const source = this.readableSource(id)
+    if (!source) return
+    return projectSource(source, this.#engine.schema)
+  }
+
+  async describeSource(id: string) {
+    const source = this.readableSource(id)
+    if (!source) return
+    const actions = await this.#engine.actionAffordances(this.principal, source)
+    return Object.freeze({
+      source: projectSource(source, this.#engine.schema),
+      relations: Object.freeze(this.relationsFrom(source)),
+      actions,
+    })
+  }
+
+  private readableSource(id: string) {
+    const source = this.#engine.repo.get(id)
+    return source &&
+      this.#engine.readAccess(this.principal, source) !== "denied"
+      ? source
+      : undefined
+  }
+
+  private relationsFrom(source: Source) {
+    return this.#engine.graph.linksFrom(source.path).map((edge) => {
+      const common = {
+        rel: edge.directive?.name ?? "link",
+        qualifiers: Object.freeze([...(edge.directive?.qualifiers ?? [])]),
+        href: edge.href,
+        ...(edge.label ? { label: edge.label } : {}),
+        ...(edge.fragment ? { fragment: edge.fragment } : {}),
+      }
+      if (edge.type === "source" && edge.to) {
+        const target = this.#engine.repo.atPath(edge.to)
+        if (
+          target &&
+          this.#engine.readAccess(this.principal, target) !== "denied"
+        ) {
+          return Object.freeze({
+            ...common,
+            type: "source" as const,
+            target: Object.freeze({ type: "source" as const, id: target.id }),
+          })
+        }
+        return Object.freeze({
+          ...common,
+          type: "unresolved" as const,
+        })
+      }
+      if (edge.type === "actor-relative") {
+        const target = actorRelativeSource(
+          this.#engine,
+          this.principal,
+          edge.href,
+        )
+        if (
+          target &&
+          this.#engine.readAccess(this.principal, target) !== "denied"
+        ) {
+          return Object.freeze({
+            ...common,
+            type: "source" as const,
+            target: Object.freeze({ type: "source" as const, id: target.id }),
+          })
+        }
+      }
+      return Object.freeze({
+        ...common,
+        type: edge.type,
+      })
+    })
+  }
+}
+
+/** @internal Construct only from a CredentialSession admitted by a host. */
+export function createView(engine: Engine, session: CredentialSession): View {
+  return new EngineView(engine, identityFor(session), principalFor(session))
+}
+
+/** @internal Create a trusted local inspection View without a credential session. */
+export function createInspectionView(engine: Engine, actor?: Actor): View {
+  return new EngineView(
+    engine,
+    actor
+      ? Object.freeze({ type: "inspection", subject: actor })
+      : Object.freeze({ type: "anonymous" }),
+    actor ? Object.freeze({ type: "actor", actor }) : { type: "anonymous" },
+  )
+}