@pathmx/core 0.5.0

package/plugins/preset.ts

@@ -0,0 +1,65 @@
+import type { Plugin, PluginFactory } from "./types.ts"
+
+/** An ordered, nestable composition recipe with no runtime identity of its own. */
+export type PluginPreset = readonly PluginContribution[]
+
+export type PluginContribution = Plugin | PluginFactory | PluginPreset
+
+type PluginLeaf = Plugin | PluginFactory
+
+/** Define an immutable Plugin composition recipe. */
+export function definePreset(
+  contributions: readonly PluginContribution[],
+): PluginPreset {
+  return Object.freeze([...contributions])
+}
+
+function isPlugin(value: unknown): value is Plugin {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    typeof value.id === "string"
+  )
+}
+
+/** Flatten nested presets in declaration order before Plugin registration. */
+export function expandPluginContributions(
+  contributions: readonly unknown[],
+): readonly PluginLeaf[] {
+  const leaves: PluginLeaf[] = []
+  const active = new Set<readonly unknown[]>()
+
+  function visit(contribution: unknown, location: string) {
+    if (Array.isArray(contribution)) {
+      if (active.has(contribution)) {
+        throw new Error(`Cyclic PluginPreset at ${location}.`)
+      }
+      active.add(contribution)
+      contribution.forEach((nested, index) =>
+        visit(nested, `${location}[${index}]`),
+      )
+      active.delete(contribution)
+      return
+    }
+    if (typeof contribution === "function" || isPlugin(contribution)) {
+      leaves.push(contribution as PluginLeaf)
+      return
+    }
+    throw new Error(
+      `Invalid Plugin contribution at ${location}: expected a Plugin, PluginFactory, or PluginPreset.`,
+    )
+  }
+
+  contributions.forEach((contribution, index) =>
+    visit(contribution, `plugins[${index}]`),
+  )
+  return Object.freeze(leaves)
+}
+
+export function instantiatePlugin(plugin: PluginLeaf): Plugin {
+  if (typeof plugin !== "function") return plugin
+  const instance = plugin()
+  if (!instance.name && plugin.name) instance.name = plugin.name
+  return instance
+}

package/plugins/query/index.ts

@@ -0,0 +1,322 @@
+import { posixPath } from "../../path.ts"
+import { queryRecordValue, type QueryField } from "../../query/fields.ts"
+import { queryDependency, queryPlanFields } from "../../query/kernel.ts"
+import type { QueryRequest, SourceQueryRequest } from "../../query/model.ts"
+import { isFenceClose, matchFenceOpen } from "../../source/index.ts"
+import { escapeHtml } from "../../util.ts"
+import { authoredViewTag } from "../../view/syntax.ts"
+import {
+  defineViewComponent,
+  type AppContext,
+  type CompileContext,
+  type PageContext,
+  type Plugin,
+  type ViewContext,
+} from "../types.ts"
+
+const QUERY_COMPONENT = "query:results"
+const QUERY_TAG = authoredViewTag(QUERY_COMPONENT)
+
+type StockView =
+  | Readonly<{ type: "list" }>
+  | Readonly<{ type: "table"; columns: readonly string[] }>
+  | Readonly<{
+      type: "components"
+      component: string
+      props: Readonly<Record<string, string>>
+    }>
+
+type CompiledStockView =
+  | Readonly<{ type: "list" }>
+  | Readonly<{ type: "table"; columns: readonly QueryField[] }>
+  | (Extract<StockView, { type: "components" }> &
+      Readonly<{ prepared: unknown }>)
+
+type CompiledQuery = Readonly<{
+  query: string
+  request: QueryRequest<unknown>
+  view: CompiledStockView
+}>
+
+function record(value: unknown, subject: string) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${subject} must be an object.`)
+  }
+  return value as Record<string, unknown>
+}
+
+function componentProps(value: unknown) {
+  if (value === undefined) return Object.freeze({})
+  const props = record(value, "Query component props")
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(props).map(([key, item]) => {
+        if (
+          item == null ||
+          (typeof item !== "string" &&
+            typeof item !== "number" &&
+            typeof item !== "boolean")
+        ) {
+          throw new Error(`Query component prop ${key} must be a scalar.`)
+        }
+        return [key, String(item)]
+      }),
+    ),
+  )
+}
+
+function requireKeys(
+  value: Readonly<Record<string, unknown>>,
+  allowed: readonly string[],
+  subject: string,
+) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key))
+      throw new Error(`Unknown ${subject} field: ${key}`)
+  }
+}
+
+function viewConfig(value: unknown): StockView {
+  if (value === undefined) return Object.freeze({ type: "list" })
+  if (typeof value === "string") {
+    if (value === "list") return Object.freeze({ type: "list" })
+    throw new Error(`Unsupported query view: ${value}`)
+  }
+  const config = record(value, "Query view")
+  const type = config.type ?? "list"
+  if (type === "list") {
+    requireKeys(config, ["type"], "query list view")
+    return Object.freeze({ type })
+  }
+  if (type === "table") {
+    requireKeys(config, ["type", "columns"], "query table view")
+    const columns = config.columns ?? []
+    if (
+      !Array.isArray(columns) ||
+      columns.some((column) => typeof column !== "string" || !column.trim())
+    ) {
+      throw new Error("Query table columns must be a list of field names.")
+    }
+    return Object.freeze({
+      type,
+      columns: Object.freeze(columns.map((column) => column.trim())),
+    })
+  }
+  if (type === "components") {
+    requireKeys(config, ["type", "component", "props"], "query components view")
+    if (typeof config.component !== "string" || !config.component.trim()) {
+      throw new Error("Query components view requires component.")
+    }
+    return Object.freeze({
+      type,
+      component: config.component.trim(),
+      props: componentProps(config.props),
+    })
+  }
+  throw new Error(`Unsupported query view: ${String(type)}`)
+}
+
+function authoredScope(value: unknown, ctx: CompileContext) {
+  const base = posixPath.dirname(ctx.source.path)
+  if (value === undefined || value === ".") return base
+  if (typeof value !== "string") throw new Error("Query from must be a string.")
+  if (value.startsWith("~/") || value.startsWith("/")) return value
+  return posixPath.resolve(base, value)
+}
+
+function parseConfig(body: string, ctx: CompileContext, app: AppContext) {
+  const parsed = record(app.yaml.parse(body) ?? {}, "Query fence")
+  const query = parsed.query ?? "sources"
+  if (typeof query !== "string" || !query.trim()) {
+    throw new Error("Query fence query must be a string.")
+  }
+  const view = viewConfig(parsed.view)
+  const request: Record<string, unknown> = {
+    ...parsed,
+    from: authoredScope(parsed.from, ctx),
+  }
+  delete request.query
+  delete request.view
+  return { query: query.trim(), request, view }
+}
+
+async function compileQueryFence(
+  config: ReturnType<typeof parseConfig>,
+  ctx: PageContext,
+  app: AppContext,
+) {
+  const plan = await app.query.prepare(config.query, config.request)
+  ctx.depend(queryDependency(plan))
+  const base = {
+    query: config.query,
+    request: Object.freeze({ ...config.request }),
+  }
+  if (config.view.type === "table") {
+    const available = queryPlanFields(app.schema, plan)
+    const byPath = new Map(available.map((field) => [field.path, field]))
+    const paths = config.view.columns.length
+      ? config.view.columns
+      : available.slice(0, 8).map(({ path }) => path)
+    const columns = paths.map((path) => {
+      const field = byPath.get(path)
+      if (!field) throw new Error(`Unknown query table column: ${path}`)
+      return field
+    })
+    return Object.freeze({
+      ...base,
+      view: Object.freeze({ type: "table", columns: Object.freeze(columns) }),
+    }) satisfies CompiledQuery
+  }
+  if (config.view.type === "components") {
+    const prepared = await app.components.prepareData(
+      config.view.component,
+      config.view.props,
+      ctx.source,
+      ctx,
+    )
+    return Object.freeze({
+      ...base,
+      view: Object.freeze({ ...config.view, prepared }),
+    }) satisfies CompiledQuery
+  }
+  return Object.freeze({
+    ...base,
+    view: config.view,
+  }) satisfies CompiledQuery
+}
+
+async function transformQueryFences(
+  markdown: string,
+  ctx: CompileContext,
+  app: AppContext,
+) {
+  if (!/query/i.test(markdown)) return markdown
+  const lines = markdown.split(/\r?\n/)
+  const output: string[] = []
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? ""
+    const fence = matchFenceOpen(line)
+    if (!fence) {
+      output.push(line)
+      continue
+    }
+    let close = index + 1
+    while (close < lines.length && !isFenceClose(lines[close]!, fence.marker)) {
+      close++
+    }
+    if (close === lines.length) {
+      output.push(...lines.slice(index))
+      break
+    }
+    const language = fence.info.split(/\s+/, 1)[0]?.toLowerCase()
+    if (language !== "query") {
+      output.push(...lines.slice(index, close + 1))
+      index = close
+      continue
+    }
+    const config = parseConfig(
+      lines.slice(index + 1, close).join("\n"),
+      ctx,
+      app,
+    )
+    const encoded = encodeURIComponent(JSON.stringify(config))
+    output.push(
+      `${fence.indent}<${QUERY_TAG} config="${escapeHtml(encoded)}" />`,
+    )
+    index = close
+  }
+  return output.join("\n")
+}
+
+function resultLabel(result: unknown) {
+  for (const field of ["meta.title", "title", "label", "name", "id"]) {
+    const value = queryRecordValue(result, field)
+    if (typeof value === "string" || typeof value === "number") {
+      return String(value)
+    }
+  }
+  return JSON.stringify(result)
+}
+
+function renderList(results: readonly unknown[]) {
+  return `<ul class="pmx-query-list">${results
+    .map((result) => {
+      const label = escapeHtml(resultLabel(result))
+      const href = queryRecordValue(result, "href")
+      return `<li>${typeof href === "string" ? `<a href="${escapeHtml(href)}">${label}</a>` : label}</li>`
+    })
+    .join("")}</ul>`
+}
+
+function renderTable(
+  results: readonly unknown[],
+  columns: readonly QueryField[],
+) {
+  const headings = columns
+    .map((column) => `<th>${escapeHtml(column.label ?? column.path)}</th>`)
+    .join("")
+  const rows = results
+    .map(
+      (result) =>
+        `<tr>${columns
+          .map(({ path }) => {
+            const value = queryRecordValue(result, path)
+            const text =
+              value == null
+                ? ""
+                : typeof value === "object"
+                  ? JSON.stringify(value)
+                  : String(value)
+            return `<td>${escapeHtml(text)}</td>`
+          })
+          .join("")}</tr>`,
+    )
+    .join("")
+  return `<table class="pmx-query-table"><thead><tr>${headings}</tr></thead><tbody>${rows}</tbody></table>`
+}
+
+async function executeQuery(compiled: CompiledQuery, ctx: ViewContext) {
+  if (compiled.query === "sources") {
+    return ctx.view.query.sources(compiled.request as SourceQueryRequest)
+  }
+  if (compiled.query === "blocks") {
+    return ctx.view.query.blocks(compiled.request as SourceQueryRequest)
+  }
+  return ctx.view.query.run(compiled.query, compiled.request)
+}
+
+export function QueryPlugin(): Plugin {
+  const Results = defineViewComponent({
+    tag: QUERY_COMPONENT,
+    async compile(use, ctx, app) {
+      const raw = use.props.config
+      if (!raw) throw new Error(`Missing query config in ${use.origin.path}.`)
+      const config = JSON.parse(decodeURIComponent(raw)) as ReturnType<
+        typeof parseConfig
+      >
+      return compileQueryFence(config, ctx, app)
+    },
+    async render(_use, compiled, ctx, app) {
+      const results = await executeQuery(compiled, ctx)
+      const view = compiled.view
+      if (view.type === "list") return renderList(results)
+      if (view.type === "table") {
+        return renderTable(results, view.columns)
+      }
+      const rendered = await Promise.all(
+        results.map((result) =>
+          app.components.renderData(view.prepared, result, ctx),
+        ),
+      )
+      return `<div class="pmx-query-components">${rendered.join("")}</div>`
+    },
+  })
+
+  return {
+    id: "query",
+    components: [Results],
+    precompile(markdown, ctx, app) {
+      return transformQueryFences(markdown, ctx, app)
+    },
+  }
+}

package/plugins/rss/index.ts

@@ -0,0 +1,46 @@
+// @ts-nocheck just prototyping here... don't take any of this too literally...
+
+const rssPlugin = definePlugin({
+  id: "rss",
+  name: "RSS",
+  // these routes attach to the server runtime at /api/rss/<route>
+  // I'm not sure if routes should have default scoping/perms or not?
+  routes: {
+    // default is GET
+    "/feed/:blogId": (req, context) => {
+      // not real code, just a shape/idea
+      const blogId = req.params.blogId
+      const graph = context.graph
+      const posts = graph.query({ blog: blogId, type: "post" })
+      const rss = posts.map((post) => ({
+        title: post.title,
+        description: post.description,
+        url: post.url,
+        date: post.date,
+      }))
+      return new Response(JSON.stringify(rss), {
+        headers: {
+          "Content-Type": "application/rss+xml",
+        },
+      })
+    },
+    "POST /subscribe": (req, context) => {
+      const { email } = await req.json()
+      // DB our source here?
+      context.db.insert("subscriptions").values({ email }).execute()
+      return new Response(JSON.stringify({ message: "Subscribed!" }), {
+        headers: {
+          "Content-Type": "application/json",
+        },
+      })
+    },
+  },
+  actions: {
+    post: ({ title, body, blog }, context: ActionContext) => {
+      // add a .post source
+    },
+    createBlog: ({ title }: { title: string }, context: ActionContext) => {
+      // create a new blog source
+    },
+  },
+})

package/plugins/runtime/actions.ts

@@ -0,0 +1,62 @@
+import {
+  clearActionError,
+  describeActionError,
+  readActionRejection,
+  showActionError,
+} from "./error.ts"
+import type { RuntimeActionInstaller } from "./start.ts"
+
+function isActionForm(form: HTMLFormElement) {
+  try {
+    return new URL(form.action, location.href).pathname.startsWith("/actions/")
+  } catch {
+    return false
+  }
+}
+
+export const installActions: RuntimeActionInstaller = (runtime) => {
+  document.addEventListener("submit", async (event) => {
+    const form = event.target
+    if (
+      !(form instanceof HTMLFormElement) ||
+      !isActionForm(form) ||
+      runtime.isNavigating()
+    ) {
+      return
+    }
+    event.preventDefault()
+    if (form.getAttribute("data-pmx-failed") === "uncertain") return
+    const from = new URL(location.href)
+    const submitter = event instanceof SubmitEvent ? event.submitter : null
+    const body = new URLSearchParams(
+      [...new FormData(form, submitter)].filter(
+        (entry): entry is [string, string] => typeof entry[1] === "string",
+      ),
+    )
+    const load = runtime.begin({ form, submitter })
+    if (!load) return
+    clearActionError(form)
+    try {
+      const response = await fetch(form.action, {
+        method: "POST",
+        headers: {
+          Accept: "application/problem+json, text/html",
+          "Content-Type": "application/x-www-form-urlencoded",
+          Referer: from.href,
+        },
+        body,
+        redirect: "follow",
+        signal: load.signal,
+      })
+      if (!response.ok) throw await readActionRejection(response)
+      await load.apply(response, from)
+    } catch (error) {
+      if (load.signal.aborted) return
+      load.finish()
+      showActionError(form, submitter, describeActionError(error))
+      console.error("PathMX action refresh failed.", error)
+    } finally {
+      load.finish()
+    }
+  })
+}

package/plugins/runtime/client.ts

@@ -0,0 +1,8 @@
+import { installActions } from "./actions.ts"
+import { createLiveSubscription } from "./live.ts"
+import { startRuntime } from "./start.ts"
+
+startRuntime({
+  actions: installActions,
+  live: createLiveSubscription,
+})