@slotform/api 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +50 -2
- package/dist/client.d.ts +16 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +98 -0
- package/dist/client.js.map +1 -0
- package/dist/error.d.ts +2 -0
- package/dist/error.d.ts.map +1 -0
- package/dist/error.js +2 -0
- package/dist/error.js.map +1 -0
- package/dist/index.d.ts +153 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +640 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/chosen.d.ts +12 -0
- package/dist/lib/chosen.d.ts.map +1 -0
- package/dist/lib/chosen.js +18 -0
- package/dist/lib/chosen.js.map +1 -0
- package/dist/lib/cursor.d.ts +68 -0
- package/dist/lib/cursor.d.ts.map +1 -0
- package/dist/lib/cursor.js +220 -0
- package/dist/lib/cursor.js.map +1 -0
- package/dist/lib/limits.d.ts +4 -0
- package/dist/lib/limits.d.ts.map +1 -0
- package/dist/lib/limits.js +10 -0
- package/dist/lib/limits.js.map +1 -0
- package/dist/lib/local-origin.d.ts +2 -0
- package/dist/lib/local-origin.d.ts.map +1 -0
- package/dist/lib/local-origin.js +17 -0
- package/dist/lib/local-origin.js.map +1 -0
- package/dist/lib/slugify.d.ts +4 -0
- package/dist/lib/slugify.d.ts.map +1 -0
- package/dist/lib/slugify.js +26 -0
- package/dist/lib/slugify.js.map +1 -0
- package/dist/lib/window.d.ts +52 -0
- package/dist/lib/window.d.ts.map +1 -0
- package/dist/lib/window.js +70 -0
- package/dist/lib/window.js.map +1 -0
- package/dist/mcp-path.d.ts +2 -0
- package/dist/mcp-path.d.ts.map +1 -0
- package/dist/mcp-path.js +3 -0
- package/dist/mcp-path.js.map +1 -0
- package/dist/mcp.d.ts +15 -0
- package/dist/mcp.d.ts.map +1 -0
- package/dist/mcp.js +5 -0
- package/dist/mcp.js.map +1 -0
- package/dist/node/barrel.d.ts +3 -0
- package/dist/node/barrel.d.ts.map +1 -0
- package/dist/node/barrel.js +70 -0
- package/dist/node/barrel.js.map +1 -0
- package/dist/node/codegen.d.ts +10 -0
- package/dist/node/codegen.d.ts.map +1 -0
- package/dist/node/codegen.js +132 -0
- package/dist/node/codegen.js.map +1 -0
- package/dist/node/procedure-codegen.d.ts +14 -0
- package/dist/node/procedure-codegen.d.ts.map +1 -0
- package/dist/node/procedure-codegen.js +95 -0
- package/dist/node/procedure-codegen.js.map +1 -0
- package/dist/node/schema-child.d.ts +2 -0
- package/dist/node/schema-child.d.ts.map +1 -0
- package/dist/node/schema-child.js +31 -0
- package/dist/node/schema-child.js.map +1 -0
- package/dist/node/schema-source.d.ts +3 -0
- package/dist/node/schema-source.d.ts.map +1 -0
- package/dist/node/schema-source.js +33 -0
- package/dist/node/schema-source.js.map +1 -0
- package/dist/node/server-client.d.ts +19 -0
- package/dist/node/server-client.d.ts.map +1 -0
- package/dist/node/server-client.js +45 -0
- package/dist/node/server-client.js.map +1 -0
- package/dist/node/types.d.ts +42 -0
- package/dist/node/types.d.ts.map +1 -0
- package/dist/node/types.js +13 -0
- package/dist/node/types.js.map +1 -0
- package/dist/not-found.d.ts +2 -0
- package/dist/not-found.d.ts.map +1 -0
- package/dist/not-found.js +6 -0
- package/dist/not-found.js.map +1 -0
- package/dist/procedure.d.ts +188 -0
- package/dist/procedure.d.ts.map +1 -0
- package/dist/procedure.js +392 -0
- package/dist/procedure.js.map +1 -0
- package/dist/query-invalidation.d.ts +20 -0
- package/dist/query-invalidation.d.ts.map +1 -0
- package/dist/query-invalidation.js +66 -0
- package/dist/query-invalidation.js.map +1 -0
- package/dist/schema.d.ts +32 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +103 -0
- package/dist/schema.js.map +1 -0
- package/dist/types.d.ts +30 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/dist/wire.d.ts +11 -0
- package/dist/wire.d.ts.map +1 -0
- package/dist/wire.js +26 -0
- package/dist/wire.js.map +1 -0
- package/dist/worker/guards.d.ts +6 -0
- package/dist/worker/guards.d.ts.map +1 -0
- package/dist/worker/guards.js +29 -0
- package/dist/worker/guards.js.map +1 -0
- package/dist/worker/index.d.ts +57 -0
- package/dist/worker/index.d.ts.map +1 -0
- package/dist/worker/index.js +418 -0
- package/dist/worker/index.js.map +1 -0
- package/dist/worker/mcp.d.ts +28 -0
- package/dist/worker/mcp.d.ts.map +1 -0
- package/dist/worker/mcp.js +361 -0
- package/dist/worker/mcp.js.map +1 -0
- package/dist/worker/request-log.d.ts +10 -0
- package/dist/worker/request-log.d.ts.map +1 -0
- package/dist/worker/request-log.js +37 -0
- package/dist/worker/request-log.js.map +1 -0
- package/guide/add-a-procedure.md +42 -0
- package/guide/background.md +86 -0
- package/guide/client.md +93 -0
- package/guide/config.md +85 -0
- package/guide/mcp.md +68 -0
- package/guide/middleware.md +79 -0
- package/guide/procedures.md +95 -0
- package/guide/utilities.md +135 -0
- package/package.json +120 -3
- package/src/client.ts +129 -0
- package/src/error.ts +1 -0
- package/src/index.ts +787 -0
- package/src/lib/chosen.ts +31 -0
- package/src/lib/cursor.ts +354 -0
- package/src/lib/limits.ts +10 -0
- package/src/lib/local-origin.ts +18 -0
- package/src/lib/slugify.ts +29 -0
- package/src/lib/window.ts +155 -0
- package/src/mcp-path.ts +2 -0
- package/src/mcp.ts +30 -0
- package/src/node/barrel.ts +77 -0
- package/src/node/codegen.ts +173 -0
- package/src/node/procedure-codegen.ts +131 -0
- package/src/node/schema-child.ts +31 -0
- package/src/node/schema-source.ts +45 -0
- package/src/node/server-client.ts +67 -0
- package/src/node/types.ts +64 -0
- package/src/not-found.ts +6 -0
- package/src/procedure.ts +935 -0
- package/src/query-invalidation.ts +106 -0
- package/src/schema.ts +133 -0
- package/src/types.ts +72 -0
- package/src/wire.ts +34 -0
- package/src/worker/guards.ts +37 -0
- package/src/worker/index.ts +681 -0
- package/src/worker/mcp.ts +470 -0
- package/src/worker/request-log.ts +50 -0
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { and, type SQL, sql } from "drizzle-orm";
|
|
2
|
+
import type { SQLiteColumn } from "drizzle-orm/sqlite-core";
|
|
3
|
+
import type { Selector } from "../schema.ts";
|
|
4
|
+
|
|
5
|
+
export interface ChosenOptions<Q> {
|
|
6
|
+
/** The table's id column. */
|
|
7
|
+
id: SQLiteColumn;
|
|
8
|
+
/** The where clause of the read's query, the one its list procedure builds from the same input. */
|
|
9
|
+
where: (query: Q) => SQL | undefined;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
// A D1 statement binds at most 100 values, so a list of ids travels as one
|
|
13
|
+
// JSON value that `json_each` expands.
|
|
14
|
+
function idList(ids: readonly string[]): SQL {
|
|
15
|
+
return sql`(select value from json_each(${JSON.stringify(ids)}))`;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** The rows a selector names, as a where clause: `{ ids }` those rows, `{ query, except }` every row the query matches but the excepted. Each list binds one value, whatever its length. */
|
|
19
|
+
export function chosenWhere<Q>(
|
|
20
|
+
selection: Selector<Q>,
|
|
21
|
+
options: ChosenOptions<Q>,
|
|
22
|
+
): SQL {
|
|
23
|
+
const { id } = options;
|
|
24
|
+
if ("ids" in selection) return sql`${id} in ${idList(selection.ids)}`;
|
|
25
|
+
const matching = options.where(selection.query);
|
|
26
|
+
const kept =
|
|
27
|
+
selection.except.length > 0
|
|
28
|
+
? sql`${id} not in ${idList(selection.except)}`
|
|
29
|
+
: undefined;
|
|
30
|
+
return and(matching, kept) ?? sql`1 = 1`;
|
|
31
|
+
}
|
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
import {
|
|
2
|
+
and,
|
|
3
|
+
asc,
|
|
4
|
+
Column,
|
|
5
|
+
desc,
|
|
6
|
+
eq,
|
|
7
|
+
getTableColumns,
|
|
8
|
+
gt,
|
|
9
|
+
gte,
|
|
10
|
+
is,
|
|
11
|
+
isNull,
|
|
12
|
+
lt,
|
|
13
|
+
lte,
|
|
14
|
+
or,
|
|
15
|
+
type SQL,
|
|
16
|
+
sql,
|
|
17
|
+
} from "drizzle-orm";
|
|
18
|
+
import type { SQLiteColumn } from "drizzle-orm/sqlite-core";
|
|
19
|
+
import { ApiError } from "../error.ts";
|
|
20
|
+
import { DEFAULT_LIMIT, LIMIT_CEILING } from "./limits.ts";
|
|
21
|
+
|
|
22
|
+
export { DEFAULT_LIMIT, LIMIT_CEILING } from "./limits.ts";
|
|
23
|
+
|
|
24
|
+
export type Direction = "asc" | "desc";
|
|
25
|
+
|
|
26
|
+
/** One column a page orders by. */
|
|
27
|
+
export interface Order {
|
|
28
|
+
column: SQLiteColumn;
|
|
29
|
+
direction: Direction;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** The `sort` a procedure declaring `sort: [...keys]` takes: a key of the procedure's `sorts` (else a column key of the table) and the way round. */
|
|
33
|
+
export interface SortInput<K extends string = string> {
|
|
34
|
+
column: K;
|
|
35
|
+
direction: Direction;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** What a sort key orders by: a column, or for a window an SQL expression (`sql\`${tasks.title} collate nocase\``, `bm25(...)`). */
|
|
39
|
+
export type Orderable = SQLiteColumn | SQL;
|
|
40
|
+
|
|
41
|
+
/** The sort key to ordering map a procedure names, for a key that is not a column of the table or orders by an expression. */
|
|
42
|
+
export type Sorts<K extends string = string, V = SQLiteColumn> = Record<K, V>;
|
|
43
|
+
|
|
44
|
+
type CursorValue = string | number | boolean | Date | null;
|
|
45
|
+
|
|
46
|
+
// A moment travels as `{ $date }`: the cursor is JSON, which has no date, and
|
|
47
|
+
// the page that decodes it has no column type to say a number is one.
|
|
48
|
+
function toWire(value: CursorValue): unknown {
|
|
49
|
+
return value instanceof Date ? { $date: value.getTime() } : value;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function fromWire(value: unknown): CursorValue | undefined {
|
|
53
|
+
if (typeof value === "object" && value !== null && "$date" in value) {
|
|
54
|
+
const at = (value as { $date: unknown }).$date;
|
|
55
|
+
if (typeof at !== "number") return undefined;
|
|
56
|
+
const date = new Date(at);
|
|
57
|
+
return Number.isNaN(date.getTime()) ? undefined : date;
|
|
58
|
+
}
|
|
59
|
+
return value === null ||
|
|
60
|
+
typeof value === "string" ||
|
|
61
|
+
typeof value === "number" ||
|
|
62
|
+
typeof value === "boolean"
|
|
63
|
+
? value
|
|
64
|
+
: undefined;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
// Base64 of the JSON's UTF-8 bytes: a title is not Latin-1, which `btoa` takes.
|
|
68
|
+
function toBase64(text: string): string {
|
|
69
|
+
let binary = "";
|
|
70
|
+
for (const byte of new TextEncoder().encode(text)) {
|
|
71
|
+
binary += String.fromCharCode(byte);
|
|
72
|
+
}
|
|
73
|
+
return btoa(binary);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function fromBase64(encoded: string): string {
|
|
77
|
+
const binary = atob(encoded);
|
|
78
|
+
return new TextDecoder("utf-8", { fatal: true }).decode(
|
|
79
|
+
Uint8Array.from(binary, (char) => char.charCodeAt(0)),
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** A cursor for the row after which the next page continues: the order columns' values, in order, then the row's id. */
|
|
84
|
+
export function encodeCursor(
|
|
85
|
+
values: readonly CursorValue[],
|
|
86
|
+
id: string,
|
|
87
|
+
): string {
|
|
88
|
+
return toBase64(JSON.stringify([values.map(toWire), id]));
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
export function decodeCursor(cursor: string): {
|
|
92
|
+
values: CursorValue[];
|
|
93
|
+
id: string;
|
|
94
|
+
} {
|
|
95
|
+
const malformed = () =>
|
|
96
|
+
new ApiError("BAD_REQUEST", { message: "Invalid cursor" });
|
|
97
|
+
let parsed: unknown;
|
|
98
|
+
try {
|
|
99
|
+
parsed = JSON.parse(fromBase64(cursor));
|
|
100
|
+
} catch {
|
|
101
|
+
throw malformed();
|
|
102
|
+
}
|
|
103
|
+
if (!Array.isArray(parsed) || parsed.length !== 2) throw malformed();
|
|
104
|
+
const [wire, id] = parsed as [unknown, unknown];
|
|
105
|
+
if (!Array.isArray(wire) || typeof id !== "string" || !id) throw malformed();
|
|
106
|
+
const values = wire.map(fromWire);
|
|
107
|
+
if (values.some((value) => value === undefined)) throw malformed();
|
|
108
|
+
return { values: values as CursorValue[], id };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** A limit within 1 and `LIMIT_CEILING` (the procedure's own `maxLimit` already bounded what it took), defaulting to `DEFAULT_LIMIT`. */
|
|
112
|
+
export function clampLimit(limit: number | undefined): number {
|
|
113
|
+
return Math.max(1, Math.min(limit ?? DEFAULT_LIMIT, LIMIT_CEILING));
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** Drizzle's relational `columns`, narrowed to exclusion so `id` stays; the order columns stay too, whatever it names. */
|
|
117
|
+
export type ExcludedColumns<T> = {
|
|
118
|
+
[K in Exclude<keyof T, "id">]?: false;
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
export interface PageOptions<C = object, K extends string = string> {
|
|
122
|
+
where?: SQL;
|
|
123
|
+
limit?: number;
|
|
124
|
+
/** The default order: one column, or several in precedence. `id` follows in the first one's direction. */
|
|
125
|
+
orderBy: Order | readonly Order[];
|
|
126
|
+
/** The caller's order, a procedure's `input.sort`: it replaces `orderBy` with the ordering `sorts` maps its key to (else the column of `idColumn`'s table it names), so a Table's header sort reaches the query. */
|
|
127
|
+
sort?: SortInput<K> | undefined;
|
|
128
|
+
/** The ordering each sort key stands for, where a key is not a column's name. */
|
|
129
|
+
sorts?: Partial<Sorts<K>>;
|
|
130
|
+
idColumn: SQLiteColumn;
|
|
131
|
+
columns?: C;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
export interface PaginateOptions<C = object, K extends string = string>
|
|
135
|
+
extends PageOptions<C, K> {
|
|
136
|
+
cursor?: string;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
export interface PaginatedResult<T> {
|
|
140
|
+
data: T[];
|
|
141
|
+
nextCursor: string | null;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
// An unknown sort column answers BAD_REQUEST (a procedure that declares `sort`
|
|
145
|
+
// already refuses it at the schema).
|
|
146
|
+
function orderOf(options: PageOptions<unknown, string>): Order[] {
|
|
147
|
+
const { sort, idColumn } = options;
|
|
148
|
+
if (sort) {
|
|
149
|
+
const found = sortOf(sort.column, options.sorts, idColumn);
|
|
150
|
+
if (!found || !isColumn(found)) {
|
|
151
|
+
throw new ApiError("BAD_REQUEST", {
|
|
152
|
+
message: `Cannot sort by ${sort.column}`,
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
return [{ column: found, direction: sort.direction }];
|
|
156
|
+
}
|
|
157
|
+
return Array.isArray(options.orderBy)
|
|
158
|
+
? [...options.orderBy]
|
|
159
|
+
: [options.orderBy as Order];
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
// What a sort key orders by: its entry in `sorts`, else the table's column of
|
|
163
|
+
// that name. Own keys only, so `constructor` is not a column.
|
|
164
|
+
export function sortOf(
|
|
165
|
+
key: string,
|
|
166
|
+
sorts: Readonly<Partial<Record<string, Orderable>>> | undefined,
|
|
167
|
+
idColumn: SQLiteColumn,
|
|
168
|
+
): Orderable | undefined {
|
|
169
|
+
if (sorts !== undefined && Object.hasOwn(sorts, key)) return sorts[key];
|
|
170
|
+
const columns = getTableColumns(idColumn.table);
|
|
171
|
+
return Object.hasOwn(columns, key) ? columns[key] : undefined;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function isColumn(value: Orderable): value is SQLiteColumn {
|
|
175
|
+
return is(value, Column);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
function keysOf(orders: readonly Order[], idColumn: SQLiteColumn): string[] {
|
|
179
|
+
const columns = Object.entries(getTableColumns(idColumn.table));
|
|
180
|
+
return orders.map(({ column }) => {
|
|
181
|
+
const found = columns.find(([, each]) => each === column);
|
|
182
|
+
if (!found) {
|
|
183
|
+
throw new Error(
|
|
184
|
+
`paginate: the order column ${column.name} is not a column of the table ${idColumn.table}`,
|
|
185
|
+
);
|
|
186
|
+
}
|
|
187
|
+
return found[0];
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
// What a cursor value of each column data type is: a value of another type
|
|
192
|
+
// would reach the driver, which refuses to bind it. A type not listed here is
|
|
193
|
+
// not judged.
|
|
194
|
+
const FITS: Partial<Record<string, (value: CursorValue) => boolean>> = {
|
|
195
|
+
string: (value) => typeof value === "string",
|
|
196
|
+
number: (value) => typeof value === "number",
|
|
197
|
+
boolean: (value) => typeof value === "boolean",
|
|
198
|
+
date: (value) => value instanceof Date,
|
|
199
|
+
};
|
|
200
|
+
|
|
201
|
+
function fits(column: SQLiteColumn, value: CursorValue): boolean {
|
|
202
|
+
return value === null || (FITS[column.dataType]?.(value) ?? true);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// The rows strictly after the cursor's, in order, as keyset segments read one
|
|
206
|
+
// after another. Within a segment, for columns c1..cn and id, (c1 > v1) or
|
|
207
|
+
// (c1 = v1 and c2 > v2) or ... or (all equal and id > vid), each `>` a `<` in a
|
|
208
|
+
// descending column; the id follows the first column's way. Nulls sort last,
|
|
209
|
+
// so nothing is past a null value, which compares by `is null`. A nullable
|
|
210
|
+
// column holding a value closes the segment: the rows of the same prefix with a
|
|
211
|
+
// null there follow as a segment of their own, then the shallower branches.
|
|
212
|
+
// One statement with an `or c is null` term loses the index order, and SQLite
|
|
213
|
+
// sorts the scope.
|
|
214
|
+
function segments(
|
|
215
|
+
orders: readonly Order[],
|
|
216
|
+
idColumn: SQLiteColumn,
|
|
217
|
+
cursor: { values: readonly CursorValue[]; id: string },
|
|
218
|
+
): SQL[] {
|
|
219
|
+
if (
|
|
220
|
+
cursor.values.length !== orders.length ||
|
|
221
|
+
orders.some((order, at) => !fits(order.column, cursor.values[at] ?? null))
|
|
222
|
+
) {
|
|
223
|
+
throw new ApiError("BAD_REQUEST", { message: "Invalid cursor" });
|
|
224
|
+
}
|
|
225
|
+
const steps = [
|
|
226
|
+
...orders.map((order, at) => ({
|
|
227
|
+
column: order.column,
|
|
228
|
+
direction: order.direction,
|
|
229
|
+
value: cursor.values[at] as CursorValue,
|
|
230
|
+
})),
|
|
231
|
+
{
|
|
232
|
+
column: idColumn,
|
|
233
|
+
direction: orders[0]?.direction ?? "asc",
|
|
234
|
+
value: cursor.id,
|
|
235
|
+
},
|
|
236
|
+
];
|
|
237
|
+
// Each step's column is of some type the value must match; `SQLiteColumn`
|
|
238
|
+
// does not carry it, so the comparison takes the value as `never`.
|
|
239
|
+
const equal = steps.map((step) =>
|
|
240
|
+
step.value === null
|
|
241
|
+
? isNull(step.column)
|
|
242
|
+
: eq(step.column, step.value as never),
|
|
243
|
+
);
|
|
244
|
+
const found: SQL[] = [];
|
|
245
|
+
let branches: SQL[] = [];
|
|
246
|
+
// The segment's shallowest column bounded by its value, which every branch
|
|
247
|
+
// implies: SQLite takes no range from the `or` alone and walks the scope.
|
|
248
|
+
let bound: SQL | undefined;
|
|
249
|
+
// `and` and `or` answer `undefined` only for no conditions; each here has one.
|
|
250
|
+
for (const [at, step] of [...steps.entries()].reverse()) {
|
|
251
|
+
if (step.value === null) continue;
|
|
252
|
+
const [past, from] = step.direction === "desc" ? [lt, lte] : [gt, gte];
|
|
253
|
+
branches.unshift(
|
|
254
|
+
and(...equal.slice(0, at), past(step.column, step.value as never)) as SQL,
|
|
255
|
+
);
|
|
256
|
+
bound = from(step.column, step.value as never);
|
|
257
|
+
if (step.column.notNull) continue;
|
|
258
|
+
found.push(
|
|
259
|
+
and(bound, or(...branches)) as SQL,
|
|
260
|
+
and(...equal.slice(0, at), isNull(step.column)) as SQL,
|
|
261
|
+
);
|
|
262
|
+
branches = [];
|
|
263
|
+
}
|
|
264
|
+
if (branches.length > 0) found.push(and(bound, or(...branches)) as SQL);
|
|
265
|
+
return found;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
interface QueryBuilder<T, C> {
|
|
269
|
+
findMany(config: {
|
|
270
|
+
columns?: C;
|
|
271
|
+
where?: SQL;
|
|
272
|
+
limit?: number;
|
|
273
|
+
offset?: number;
|
|
274
|
+
orderBy?: SQL[];
|
|
275
|
+
}): Promise<T[]>;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
// Drizzle's `columns` with the order columns and the id put back, which the
|
|
279
|
+
// cursor reads off the last row.
|
|
280
|
+
function withKept<C>(
|
|
281
|
+
columns: C | undefined,
|
|
282
|
+
keys: readonly string[],
|
|
283
|
+
): C | undefined {
|
|
284
|
+
if (!columns) return undefined;
|
|
285
|
+
const kept = { ...columns } as Record<string, unknown>;
|
|
286
|
+
for (const key of [...keys, "id"]) delete kept[key];
|
|
287
|
+
return kept as C;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
export function orderSql(
|
|
291
|
+
orders: readonly { column: Orderable; direction: Direction }[],
|
|
292
|
+
idColumn: SQLiteColumn,
|
|
293
|
+
): SQL[] {
|
|
294
|
+
const direction = orders[0]?.direction ?? "asc";
|
|
295
|
+
const by = direction === "desc" ? desc : asc;
|
|
296
|
+
// The id, a primary key, is never null; `nulls last` on it as a later term
|
|
297
|
+
// makes SQLite 3.54 sort an ascending page in a temp B-tree.
|
|
298
|
+
return [
|
|
299
|
+
...orders.map(
|
|
300
|
+
(order) =>
|
|
301
|
+
sql`${order.direction === "desc" ? desc(order.column) : asc(order.column)} nulls last`,
|
|
302
|
+
),
|
|
303
|
+
by(idColumn),
|
|
304
|
+
];
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
export async function paginate<
|
|
308
|
+
T extends { id: string },
|
|
309
|
+
const C extends ExcludedColumns<T> = object,
|
|
310
|
+
K extends string = string,
|
|
311
|
+
>(
|
|
312
|
+
queryBuilder: QueryBuilder<T, NoInfer<C>>,
|
|
313
|
+
options: PaginateOptions<C, K>,
|
|
314
|
+
): Promise<PaginatedResult<Omit<T, keyof C>>> {
|
|
315
|
+
const limit = clampLimit(options.limit);
|
|
316
|
+
const { idColumn } = options;
|
|
317
|
+
const orders = orderOf(options as PageOptions<unknown, string>);
|
|
318
|
+
const keys = keysOf(orders, idColumn);
|
|
319
|
+
|
|
320
|
+
// The first page is one statement: the whole order, nulls last.
|
|
321
|
+
const reads = options.cursor
|
|
322
|
+
? segments(orders, idColumn, decodeCursor(options.cursor))
|
|
323
|
+
: [undefined];
|
|
324
|
+
const columns = withKept(options.columns, keys);
|
|
325
|
+
const orderBy = orderSql(orders, idColumn);
|
|
326
|
+
const rows: T[] = [];
|
|
327
|
+
for (const segment of reads) {
|
|
328
|
+
if (rows.length > limit) break;
|
|
329
|
+
rows.push(
|
|
330
|
+
...(await queryBuilder.findMany({
|
|
331
|
+
...(columns ? { columns } : {}),
|
|
332
|
+
where: and(options.where, segment),
|
|
333
|
+
limit: limit + 1 - rows.length,
|
|
334
|
+
orderBy,
|
|
335
|
+
})),
|
|
336
|
+
);
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
const hasMore = rows.length > limit;
|
|
340
|
+
const data = hasMore ? rows.slice(0, -1) : rows;
|
|
341
|
+
const lastItem = data[data.length - 1] as Record<string, unknown> | undefined;
|
|
342
|
+
|
|
343
|
+
return {
|
|
344
|
+
data: data as Omit<T, keyof C>[],
|
|
345
|
+
nextCursor:
|
|
346
|
+
hasMore && lastItem
|
|
347
|
+
? encodeCursor(
|
|
348
|
+
// `withKept` keeps the order columns, which hold a cursor value.
|
|
349
|
+
keys.map((key) => lastItem[key] as CursorValue),
|
|
350
|
+
lastItem.id as string,
|
|
351
|
+
)
|
|
352
|
+
: null,
|
|
353
|
+
};
|
|
354
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// A page's size bounds, import-free so the procedure factory reads them
|
|
2
|
+
// without the pagination helpers' drizzle import.
|
|
3
|
+
|
|
4
|
+
// The rows a page holds unless the caller names a `limit`.
|
|
5
|
+
export const DEFAULT_LIMIT = 20;
|
|
6
|
+
// What no procedure may name as its `maxLimit`: a page this large is a table
|
|
7
|
+
// scan the client asked for by mistake.
|
|
8
|
+
export const LIMIT_CEILING = 10_000;
|
|
9
|
+
// What a paginated procedure accepts unless it names its own `maxLimit`.
|
|
10
|
+
export const MAX_LIMIT = 100;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// Local-dev hostnames: docs/architecture/plugins/api.md, "Local and dev origins".
|
|
2
|
+
const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "0.0.0.0"]);
|
|
3
|
+
|
|
4
|
+
export function isLocalOrigin(origin: string): boolean {
|
|
5
|
+
try {
|
|
6
|
+
const { hostname } = new URL(origin);
|
|
7
|
+
// `*.localhost` is reserved (RFC 6761); `*.localdomain` is common in
|
|
8
|
+
// Linux /etc/hosts.
|
|
9
|
+
return (
|
|
10
|
+
LOCAL_HOSTNAMES.has(hostname) ||
|
|
11
|
+
hostname.endsWith(".localhost") ||
|
|
12
|
+
hostname.endsWith(".localdomain")
|
|
13
|
+
);
|
|
14
|
+
} catch {
|
|
15
|
+
// A string `URL` cannot parse is not a local origin.
|
|
16
|
+
return false;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import slugifyPkg from "slugify";
|
|
2
|
+
|
|
3
|
+
// Reserved slugs: docs/architecture/plugins/auth.md, "Reserved slugs".
|
|
4
|
+
export const RESERVED_SLUGS = [
|
|
5
|
+
"admin",
|
|
6
|
+
"api",
|
|
7
|
+
"system",
|
|
8
|
+
"auth",
|
|
9
|
+
"new",
|
|
10
|
+
"settings",
|
|
11
|
+
] as const;
|
|
12
|
+
|
|
13
|
+
const reserved = new Set<string>(RESERVED_SLUGS);
|
|
14
|
+
|
|
15
|
+
// `slugify` turns text into a URL segment and never refuses; `isReservedSlug`
|
|
16
|
+
// answers whether a slug is taken by the app's own routes, so a procedure
|
|
17
|
+
// names the refusal as its own field error. A dot is a word boundary, so a
|
|
18
|
+
// domain reads as its words.
|
|
19
|
+
export function slugify(text: string): string {
|
|
20
|
+
return slugifyPkg(text.replaceAll(".", " "), {
|
|
21
|
+
lower: true,
|
|
22
|
+
strict: true,
|
|
23
|
+
trim: true,
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function isReservedSlug(slug: string): boolean {
|
|
28
|
+
return reserved.has(slug);
|
|
29
|
+
}
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
import { count, inArray, type SQL } from "drizzle-orm";
|
|
2
|
+
import type {
|
|
3
|
+
BaseSQLiteDatabase,
|
|
4
|
+
SQLiteColumn,
|
|
5
|
+
SQLiteSelect,
|
|
6
|
+
SQLiteTable,
|
|
7
|
+
} from "drizzle-orm/sqlite-core";
|
|
8
|
+
import { ApiError } from "../error.ts";
|
|
9
|
+
import {
|
|
10
|
+
clampLimit,
|
|
11
|
+
type Direction,
|
|
12
|
+
type ExcludedColumns,
|
|
13
|
+
type Orderable,
|
|
14
|
+
orderSql,
|
|
15
|
+
type SortInput,
|
|
16
|
+
sortOf,
|
|
17
|
+
} from "./cursor.ts";
|
|
18
|
+
|
|
19
|
+
/** One thing a window orders by: a column or an SQL expression, and the way round. */
|
|
20
|
+
export interface WindowOrder {
|
|
21
|
+
column: Orderable;
|
|
22
|
+
direction: Direction;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface WindowOptions<C = object, K extends string = string> {
|
|
26
|
+
where?: SQL;
|
|
27
|
+
limit?: number;
|
|
28
|
+
/** The default order: one column or expression, or several in precedence. `id` follows in the first one's direction. */
|
|
29
|
+
orderBy: WindowOrder | readonly WindowOrder[];
|
|
30
|
+
/** The caller's order, a procedure's `input.sort`: it replaces `orderBy` with what `sorts` maps its key to, so a Table's header sort reaches the query. */
|
|
31
|
+
sort?: SortInput<K> | undefined;
|
|
32
|
+
/** What each sort key orders by: a column, or an expression (`sql\`${tasks.title} collate nocase\``). A key not named here sorts by the column of `idColumn`'s table of that name. */
|
|
33
|
+
sorts?: Partial<Record<K, Orderable>>;
|
|
34
|
+
idColumn: SQLiteColumn;
|
|
35
|
+
columns?: C;
|
|
36
|
+
/** The page's first row, a procedure's `input.offset`. */
|
|
37
|
+
offset?: number;
|
|
38
|
+
/** The database: `context.db`. */
|
|
39
|
+
db: BaseSQLiteDatabase<
|
|
40
|
+
"sync" | "async",
|
|
41
|
+
unknown, // biome-ignore lint/suspicious/noExplicitAny: the schema is the consumer's
|
|
42
|
+
any
|
|
43
|
+
>;
|
|
44
|
+
/** Joins the query selects the ids and the count from (it starts at `idColumn`'s table), so `where` and the order may name a joined table: `(query) => query.innerJoin(taskSearch, eq(taskSearch.rowid, tasks.seq))`. */
|
|
45
|
+
join?: (query: SQLiteSelect) => SQLiteSelect;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export interface WindowResult<T> {
|
|
49
|
+
data: T[];
|
|
50
|
+
/** Every row the filter matches: the scroller's length. */
|
|
51
|
+
total: number;
|
|
52
|
+
offset: number;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
interface QueryBuilder<T, C> {
|
|
56
|
+
findMany(config: {
|
|
57
|
+
columns?: C;
|
|
58
|
+
where?: SQL;
|
|
59
|
+
limit?: number;
|
|
60
|
+
offset?: number;
|
|
61
|
+
orderBy?: SQL[];
|
|
62
|
+
}): Promise<T[]>;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const BATCH = 90;
|
|
66
|
+
|
|
67
|
+
function orders<K extends string>(
|
|
68
|
+
options: WindowOptions<object, K>,
|
|
69
|
+
): WindowOrder[] {
|
|
70
|
+
const { sort, idColumn } = options;
|
|
71
|
+
if (sort) {
|
|
72
|
+
const found = sortOf(sort.column, options.sorts, idColumn);
|
|
73
|
+
if (!found) {
|
|
74
|
+
throw new ApiError("BAD_REQUEST", {
|
|
75
|
+
message: `Cannot sort by ${sort.column}`,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
return [{ column: found, direction: sort.direction }];
|
|
79
|
+
}
|
|
80
|
+
return Array.isArray(options.orderBy)
|
|
81
|
+
? [...options.orderBy]
|
|
82
|
+
: [options.orderBy as WindowOrder];
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The answer of a `paginated: "window"` procedure: one page at `offset` and the filter's total, both from the one `where`, in the order `orderBy` (or the caller's `sort`) gives, then `id`.
|
|
87
|
+
*
|
|
88
|
+
* The order is decided on the ids alone (a sorter that holds a key and an id, not every column of a wide row), then the page's rows are read by id: the cost of a deep offset stays a narrow sort. The first page of a query with no `join` is read in one statement, since a top-N sort is cheap.
|
|
89
|
+
*/
|
|
90
|
+
export async function paginateWindow<
|
|
91
|
+
T extends { id: string },
|
|
92
|
+
const C extends ExcludedColumns<T> = object,
|
|
93
|
+
K extends string = string,
|
|
94
|
+
>(
|
|
95
|
+
queryBuilder: QueryBuilder<T, NoInfer<C>>,
|
|
96
|
+
options: WindowOptions<C, K>,
|
|
97
|
+
): Promise<WindowResult<Omit<T, keyof C>>> {
|
|
98
|
+
const limit = clampLimit(options.limit);
|
|
99
|
+
const offset = Math.max(0, Math.trunc(options.offset ?? 0));
|
|
100
|
+
const { idColumn, where, db, join } = options;
|
|
101
|
+
const table = idColumn.table as SQLiteTable;
|
|
102
|
+
const orderBy = orderSql(
|
|
103
|
+
orders(options as WindowOptions<object, K>),
|
|
104
|
+
idColumn,
|
|
105
|
+
);
|
|
106
|
+
const columns = options.columns ? { columns: options.columns } : {};
|
|
107
|
+
|
|
108
|
+
// A fresh query over the one source: the ids and the count must agree.
|
|
109
|
+
const source = (fields: Record<string, SQLiteColumn | SQL>) => {
|
|
110
|
+
const query = db.select(fields).from(table).$dynamic() as SQLiteSelect;
|
|
111
|
+
return (join ? join(query) : query).where(where);
|
|
112
|
+
};
|
|
113
|
+
const total = async (): Promise<number> => {
|
|
114
|
+
const [row] = (await source({ n: count() })) as { n: number }[];
|
|
115
|
+
return row?.n ?? 0;
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
if (offset === 0 && !join) {
|
|
119
|
+
const [data, n] = await Promise.all([
|
|
120
|
+
queryBuilder.findMany({ ...columns, where, limit, orderBy }),
|
|
121
|
+
total(),
|
|
122
|
+
]);
|
|
123
|
+
return { data: data as Omit<T, keyof C>[], total: n, offset };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
const [ids, n] = await Promise.all([
|
|
127
|
+
(async () =>
|
|
128
|
+
(
|
|
129
|
+
(await source({ id: idColumn })
|
|
130
|
+
.orderBy(...orderBy)
|
|
131
|
+
.limit(limit)
|
|
132
|
+
.offset(offset)) as { id: string }[]
|
|
133
|
+
).map((row) => row.id))(),
|
|
134
|
+
total(),
|
|
135
|
+
]);
|
|
136
|
+
if (ids.length === 0) return { data: [], total: n, offset };
|
|
137
|
+
// A D1 statement binds at most 100 values: a long page is read in batches.
|
|
138
|
+
const batches: string[][] = [];
|
|
139
|
+
for (let at = 0; at < ids.length; at += BATCH) {
|
|
140
|
+
batches.push(ids.slice(at, at + BATCH));
|
|
141
|
+
}
|
|
142
|
+
const rows = (
|
|
143
|
+
await Promise.all(
|
|
144
|
+
batches.map((batch) =>
|
|
145
|
+
queryBuilder.findMany({ ...columns, where: inArray(idColumn, batch) }),
|
|
146
|
+
),
|
|
147
|
+
)
|
|
148
|
+
).flat();
|
|
149
|
+
const byId = new Map(rows.map((row) => [row.id, row]));
|
|
150
|
+
const data = ids.flatMap((id) => {
|
|
151
|
+
const row = byId.get(id);
|
|
152
|
+
return row ? [row] : [];
|
|
153
|
+
});
|
|
154
|
+
return { data: data as Omit<T, keyof C>[], total: n, offset };
|
|
155
|
+
}
|
package/src/mcp-path.ts
ADDED
package/src/mcp.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { Procedure } from "./types.ts";
|
|
2
|
+
|
|
3
|
+
// Every dotted path in a router that names a procedure (`pages.list`), and
|
|
4
|
+
// none that names a namespace.
|
|
5
|
+
export type ProcedurePath<TRoutes, TPrefix extends string = ""> = {
|
|
6
|
+
[K in keyof TRoutes & string]: TRoutes[K] extends Procedure<
|
|
7
|
+
infer _TInput,
|
|
8
|
+
infer _TOutput
|
|
9
|
+
>
|
|
10
|
+
? `${TPrefix}${K}`
|
|
11
|
+
: TRoutes[K] extends Record<string, unknown>
|
|
12
|
+
? ProcedurePath<TRoutes[K], `${TPrefix}${K}.`>
|
|
13
|
+
: never;
|
|
14
|
+
}[keyof TRoutes & string];
|
|
15
|
+
|
|
16
|
+
export interface McpDefinition {
|
|
17
|
+
// What the agent reads once connected: the product and how to use its tools.
|
|
18
|
+
// The worker appends the line naming the grant's organization.
|
|
19
|
+
instructions: string;
|
|
20
|
+
// Router path to the description the agent reads, in the order it lists.
|
|
21
|
+
tools: Partial<Record<string, string>>;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
// `defineMcp`: docs/architecture/plugins/api.md, "MCP".
|
|
25
|
+
export function defineMcp<TRoutes>(definition: {
|
|
26
|
+
instructions: string;
|
|
27
|
+
tools: { [K in ProcedurePath<TRoutes>]?: string };
|
|
28
|
+
}): McpDefinition {
|
|
29
|
+
return definition;
|
|
30
|
+
}
|