@pathmx/core 0.5.0

package/query/fields.ts

@@ -0,0 +1,216 @@
+import type { QueryScalar } from "./model.ts"
+
+type JsonSchema = Readonly<Record<string, unknown>>
+
+export type QueryField = Readonly<{
+  path: string
+  label?: string
+  description?: string
+  filterable: boolean
+  sortable: boolean
+}>
+
+/** @internal Read a discoverable field from a query projection or its data map. */
+export function queryRecordValue(record: unknown, path: string): unknown {
+  const segments = path.split(".")
+  const read = (value: unknown, parts: readonly string[]) => {
+    let current = value
+    for (const segment of parts) {
+      if (current == null || typeof current !== "object") return
+      current = (current as Record<string, unknown>)[segment]
+    }
+    return current
+  }
+  const direct = read(record, segments)
+  if (direct !== undefined) return direct
+  if (segments[0] === "source") {
+    const source = read(record, ["source"])
+    const nested = read(source, segments.slice(1))
+    if (nested !== undefined) return nested
+    const sourceData = read(source, ["data"])
+    const nestedData = read(sourceData, segments.slice(1))
+    if (nestedData !== undefined) return nestedData
+  }
+  return read(read(record, ["data"]), segments)
+}
+
+function object(value: unknown): JsonSchema | undefined {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+    ? (value as JsonSchema)
+    : undefined
+}
+
+function reference(root: JsonSchema, value: unknown) {
+  if (typeof value !== "string" || !value.startsWith("#/")) return
+  let current: unknown = root
+  for (const encoded of value.slice(2).split("/")) {
+    const node = object(current)
+    if (!node) return
+    const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~")
+    current = node[key]
+  }
+  return object(current)
+}
+
+function dereference(root: JsonSchema, schema: JsonSchema) {
+  return reference(root, schema.$ref) ?? schema
+}
+
+function scalarType(value: unknown) {
+  const types = Array.isArray(value) ? value : [value]
+  return (
+    types.length > 0 &&
+    types.every(
+      (type) =>
+        type === "string" ||
+        type === "number" ||
+        type === "integer" ||
+        type === "boolean" ||
+        type === "null",
+    )
+  )
+}
+
+function scalarSchema(root: JsonSchema, raw: JsonSchema): boolean {
+  const schema = dereference(root, raw)
+  if (scalarType(schema.type)) return true
+  if (
+    Object.hasOwn(schema, "const") &&
+    (schema.const == null ||
+      typeof schema.const === "string" ||
+      typeof schema.const === "number" ||
+      typeof schema.const === "boolean")
+  ) {
+    return true
+  }
+  if (
+    Array.isArray(schema.enum) &&
+    schema.enum.length > 0 &&
+    schema.enum.every(
+      (value) =>
+        value == null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean",
+    )
+  ) {
+    return true
+  }
+  for (const option of [schema.anyOf, schema.oneOf]) {
+    if (
+      Array.isArray(option) &&
+      option.length > 0 &&
+      option.every((candidate) => {
+        const nested = object(candidate)
+        return nested ? scalarSchema(root, nested) : false
+      })
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+function collect(
+  root: JsonSchema,
+  raw: JsonSchema,
+  prefix: string,
+  fields: Map<string, QueryField>,
+) {
+  const schema = dereference(root, raw)
+  if (prefix && scalarSchema(root, schema)) {
+    fields.set(
+      prefix,
+      Object.freeze({
+        path: prefix,
+        ...(typeof schema.title === "string" ? { label: schema.title } : {}),
+        ...(typeof schema.description === "string"
+          ? { description: schema.description }
+          : {}),
+        filterable: true,
+        sortable: true,
+      }),
+    )
+    return
+  }
+  const properties = object(schema.properties)
+  if (properties) {
+    for (const [name, candidate] of Object.entries(properties)) {
+      const nested = object(candidate)
+      if (!nested) continue
+      collect(root, nested, prefix ? `${prefix}.${name}` : name, fields)
+    }
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const candidate of schema.allOf) {
+      const nested = object(candidate)
+      if (nested) collect(root, nested, prefix, fields)
+    }
+  }
+}
+
+export class QueryFieldCatalog {
+  private fields = new Map<string, QueryField>()
+
+  add(path: string, label?: string) {
+    this.fields.set(
+      path,
+      Object.freeze({
+        path,
+        ...(label ? { label } : {}),
+        filterable: true,
+        sortable: true,
+      }),
+    )
+    return this
+  }
+
+  addObjectSchema(schema: JsonSchema, prefix = "") {
+    collect(schema, schema, prefix, this.fields)
+    return this
+  }
+
+  addArrayOutput(schema: JsonSchema) {
+    const root = dereference(schema, schema)
+    const type = root.type
+    if (type !== "array" && !(Array.isArray(type) && type.includes("array"))) {
+      throw new Error("Query output JSON Schema must describe an array.")
+    }
+    const items = object(root.items)
+    if (!items) {
+      throw new Error("Query output JSON Schema must describe array items.")
+    }
+    collect(schema, items, "", this.fields)
+    return this
+  }
+
+  has(path: string) {
+    return this.fields.has(path)
+  }
+
+  require(path: string, operation: "filter" | "sort") {
+    const field = this.fields.get(path)
+    const supported =
+      operation === "filter" ? field?.filterable : field?.sortable
+    if (!supported) {
+      throw new Error(`Field ${path} does not support query ${operation}.`)
+    }
+  }
+
+  list() {
+    return Object.freeze(
+      [...this.fields.values()].sort((left, right) =>
+        left.path.localeCompare(right.path),
+      ),
+    )
+  }
+}
+
+export function queryScalar(value: unknown): value is QueryScalar {
+  return (
+    value == null ||
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isFinite(value)) ||
+    typeof value === "boolean"
+  )
+}

package/query/invalidation.ts

@@ -0,0 +1,48 @@
+import type { Dependency } from "../dependencies.ts"
+import type { Engine } from "../host/engine.ts"
+import type { RouteInvalidations } from "../invalidation.ts"
+import { queryDependency } from "./kernel.ts"
+import type { Source } from "../source/index.ts"
+
+type QueryInvalidation = Readonly<{
+  key: string
+  actors?: readonly string[]
+}>
+
+function addRoutes(
+  engine: Engine,
+  routes: RouteInvalidations,
+  queries: Iterable<QueryInvalidation>,
+) {
+  for (const query of queries) {
+    for (const pagePath of engine.dependentsOf(queryDependency(query))) {
+      const page = engine.pageCache.get(pagePath)
+      if (!page) continue
+      if (query.actors) routes.addActors(page.route, query.actors)
+      else routes.add(page.route)
+    }
+  }
+}
+
+/** @internal Map derived query invalidation back onto compiled route consumers. */
+export function dependencies(
+  engine: Engine,
+  routes: RouteInvalidations,
+  dependencies: Iterable<Dependency>,
+) {
+  addRoutes(engine, routes, engine.queries.invalidateDependencies(dependencies))
+}
+
+/** @internal Invalidate one canonical Source transition and its derived routes. */
+export function source(
+  engine: Engine,
+  routes: RouteInvalidations,
+  before: Source | undefined,
+  after: Source | undefined,
+  path: string,
+) {
+  addRoutes(engine, routes, [
+    ...engine.queries.transition(before, after),
+    ...engine.queries.invalidateDependencies([{ type: "source", path }]),
+  ])
+}