src/doc-reads.ts

Functions

Imports

It imports src/limits.ts. Imported by src/doc-index.ts, src/portal-library.ts, src/tools/docs-read.ts.

Source

1import { SEARCH_ROWS } from "./limits";
2
3// The document reads the docs tool (src/tools/docs-read.ts) and the Portal's Library
4// (src/portal-library.ts) share, so the two cannot disagree about what a search finds,
5// what a document holds or which edges touch it (conventions 1.2, never build the same
6// thing twice).
7
8export interface DocumentRow {
9  id: number;
10  namespace: string;
11  path: string;
12  title: string | null;
13  type: string;
14  status: string;
15  tags: string | null;
16  created_at: string;
17  updated_at: string;
18  body: string;
19}
20
21export interface SearchRow {
22  id: number;
23  namespace: string;
24  path: string;
25  title: string | null;
26  type: string;
27  status: string;
28  updated_at: string;
29  snippet: string;
30}
31
32export interface DocumentEdges {
33  outgoing: Array<{ type: string; to_ns: string; to_path: string }>;
34  incoming: Array<{ type: string; from_ns: string; from_path: string }>;
35}
36
37/** One document by namespace and path, or null. Named columns: frontmatter and
38 *  publish_at are left out, since nothing in this server reads or writes them. */
39export async function readDocument(db: D1Database, namespace: string, path: string): Promise<DocumentRow | null> {
40  return db
41    .prepare(
42      `SELECT id, namespace, path, title, type, status, tags, created_at, updated_at, body
43       FROM documents WHERE namespace = ?1 AND path = ?2`
44    )
45    .bind(namespace, path)
46    .first<DocumentRow>();
47}
48
49/** The typed edges declared on a document and the ones pointing at it. */
50export async function documentEdges(db: D1Database, namespace: string, path: string): Promise<DocumentEdges> {
51  const [outgoing, incoming] = await Promise.all([
52    db
53      .prepare("SELECT type, to_ns, to_path FROM document_links WHERE from_ns = ?1 AND from_path = ?2 ORDER BY type, to_ns, to_path")
54      .bind(namespace, path)
55      .all<DocumentEdges["outgoing"][number]>(),
56    db
57      .prepare("SELECT type, from_ns, from_path FROM document_links WHERE to_ns = ?1 AND to_path = ?2 ORDER BY type, from_ns, from_path")
58      .bind(namespace, path)
59      .all<DocumentEdges["incoming"][number]>(),
60  ]);
61  return { outgoing: outgoing.results, incoming: incoming.results };
62}
63
64export interface SearchFilter {
65  namespace: string | null;
66  type: string | null;
67  /** A JSON array of the only paths a row may have, or null for no such limit. */
68  allowed: string | null;
69  /** The marks snippet() puts around a matched word. The docs tool's answer uses [ and ];
70   *  the Portal passes marks no document text holds, so a bracket in the text (a Markdown
71   *  link, say) is never read as a match. */
72  marks?: { open: string; close: string };
73}
74
75/** Full text search, ranked by bm25, at most SEARCH_ROWS + 1 rows, so a caller can tell
76 *  "exactly the limit" from "there are more". Hyphens, quotes and bare AND, OR and NOT
77 *  are FTS5 syntax, so a query FTS5 refuses is retried once as a quoted phrase, and plain
78 *  text is always a safe input. A second refusal throws. */
79export async function searchDocuments(db: D1Database, query: string, filter: SearchFilter): Promise<SearchRow[]> {
80  const run = (match: string) =>
81    db
82      .prepare(
83        `SELECT d.id, d.namespace, d.path, d.title, d.type, d.status, d.updated_at,
84                snippet(documents_fts, 1, ?6, ?7, ' ... ', 16) AS snippet
85         FROM documents_fts
86         JOIN documents d ON d.id = documents_fts.rowid
87         WHERE documents_fts MATCH ?1
88           AND (?2 IS NULL OR d.namespace = ?2)
89           AND (?3 IS NULL OR d.type = ?3)
90           AND (?4 IS NULL OR d.path IN (SELECT value FROM json_each(?4)))
91         ORDER BY bm25(documents_fts)
92         LIMIT ?5`
93      )
94      .bind(match, filter.namespace, filter.type, filter.allowed, SEARCH_ROWS + 1, filter.marks?.open ?? "[", filter.marks?.close ?? "]")
95      .all<SearchRow>();
96  try {
97    return (await run(query)).results;
98  } catch {
99    return (await run(`"${query.replace(/"/g, '""')}"`)).results;
100  }
101}