@slotform/api 0.0.0-stage → 0.1.0
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
package/src/client.ts
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
import { createORPCClient } from "@orpc/client";
|
|
2
|
+
import { RPCLink } from "@orpc/client/fetch";
|
|
3
|
+
import { captureEntityHeaders } from "./query-invalidation.ts";
|
|
4
|
+
import type { RouterClient } from "./types.ts";
|
|
5
|
+
import { SLOTFORM_NOT_FOUND_HEADER } from "./wire.ts";
|
|
6
|
+
|
|
7
|
+
export { isNotFound } from "./not-found.ts";
|
|
8
|
+
export type { RouterClient } from "./types.ts";
|
|
9
|
+
|
|
10
|
+
// Default client registration: docs/architecture/plugins/api.md, "Client".
|
|
11
|
+
let registeredApiClient: unknown;
|
|
12
|
+
|
|
13
|
+
export function registerApiClient(client: unknown): void {
|
|
14
|
+
registeredApiClient = client;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
// Read by the query plugin's org-rules fetch and by `createClient`'s
|
|
18
|
+
// auto-registration guard. Not a consumer-facing surface -- there's nothing
|
|
19
|
+
// to inspect on the value beyond "is a client registered".
|
|
20
|
+
export function getRegisteredApiClient(): unknown {
|
|
21
|
+
return registeredApiClient;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface ClientConfig {
|
|
25
|
+
/** The RPC endpoint (`/rpc` by default). A function is read on every request, so an app whose server is chosen while it runs (a phone signing in to a server it is told the address of) changes the address without rebuilding the client. Clear the query cache when it changes: the data held is the old server's. */
|
|
26
|
+
url?: string | (() => string);
|
|
27
|
+
fetch?: typeof globalThis.fetch;
|
|
28
|
+
credentials?: RequestCredentials;
|
|
29
|
+
/** Sent with every request: an object, or a function read on every request that may answer later (a cookie or a key read from the device's secure store). */
|
|
30
|
+
headers?:
|
|
31
|
+
| Record<string, string>
|
|
32
|
+
| (() => Record<string, string> | Promise<Record<string, string>>);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// Derives the procedure pathKey ("todos/list") from a request URL by
|
|
36
|
+
// stripping the configured base's pathname. `base` is either relative
|
|
37
|
+
// ("/rpc") or absolute ("https://host/rpc"); both cases resolve through
|
|
38
|
+
// `URL` against a dummy origin so the pathname strip is identical either way.
|
|
39
|
+
function pathKeyFromRequestUrl(requestUrl: string, base: string): string {
|
|
40
|
+
const basePath = new URL(base, "http://slotform.invalid").pathname;
|
|
41
|
+
const path = new URL(requestUrl, "http://slotform.invalid").pathname;
|
|
42
|
+
const trimmedBase = basePath.replace(/^\/|\/$/g, "");
|
|
43
|
+
const trimmedPath = path.replace(/^\/|\/$/g, "");
|
|
44
|
+
return trimmedPath.startsWith(trimmedBase)
|
|
45
|
+
? trimmedPath.slice(trimmedBase.length).replace(/^\/+/, "")
|
|
46
|
+
: trimmedPath;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// oRPC's RPCLink resolves every request URL via `new URL(baseUrl)` with no
|
|
50
|
+
// `base` argument, so a relative default like "/rpc" throws "Invalid URL" on
|
|
51
|
+
// the first real call. Resolve against `location.origin` when present (any
|
|
52
|
+
// browser); native/SSR/test callers keep passing an absolute `url` (as the
|
|
53
|
+
// README's Expo example already does), so this is a no-op for them.
|
|
54
|
+
function resolveClientUrl(url: string): string {
|
|
55
|
+
if (/^[a-z][a-z\d+\-.]*:\/\//i.test(url)) return url;
|
|
56
|
+
if (typeof location === "undefined") return url;
|
|
57
|
+
return new URL(url, location.origin).toString();
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// Operation context handed over by the query plugin: docs/architecture/plugins/api.md, "Client".
|
|
61
|
+
let operationContext: symbol | undefined;
|
|
62
|
+
|
|
63
|
+
export function registerOperationContext(symbol: symbol): void {
|
|
64
|
+
operationContext = symbol;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
// The operation types oRPC's own docs send as GET.
|
|
68
|
+
const READ_OPERATIONS = new Set(["query", "streamed", "live", "infinite"]);
|
|
69
|
+
|
|
70
|
+
// Reads travel as GET: docs/architecture/plugins/api.md, "Reads travel as GET".
|
|
71
|
+
function methodOf(options: { context: object }): "GET" | "POST" {
|
|
72
|
+
if (operationContext === undefined) return "POST";
|
|
73
|
+
const operation = (
|
|
74
|
+
options.context as Record<symbol, { type?: string } | undefined>
|
|
75
|
+
)[operationContext];
|
|
76
|
+
return operation?.type && READ_OPERATIONS.has(operation.type)
|
|
77
|
+
? "GET"
|
|
78
|
+
: "POST";
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export function createClient<TRouter>(
|
|
82
|
+
config?: ClientConfig,
|
|
83
|
+
): RouterClient<TRouter> {
|
|
84
|
+
const given = config?.url ?? "/rpc";
|
|
85
|
+
// The address now: a function is asked each time, a string once.
|
|
86
|
+
const urlNow = (): string =>
|
|
87
|
+
resolveClientUrl(typeof given === "function" ? given() : given);
|
|
88
|
+
const baseFetch = config?.fetch ?? globalThis.fetch;
|
|
89
|
+
|
|
90
|
+
const link = new RPCLink({
|
|
91
|
+
url: typeof given === "function" ? urlNow : urlNow(),
|
|
92
|
+
method: methodOf,
|
|
93
|
+
headers: config?.headers,
|
|
94
|
+
fetch: async (request, init) => {
|
|
95
|
+
const response = await baseFetch(request, {
|
|
96
|
+
...init,
|
|
97
|
+
credentials: config?.credentials ?? "include",
|
|
98
|
+
});
|
|
99
|
+
try {
|
|
100
|
+
captureEntityHeaders(
|
|
101
|
+
pathKeyFromRequestUrl(request.url, urlNow()),
|
|
102
|
+
response.headers,
|
|
103
|
+
);
|
|
104
|
+
} catch {
|
|
105
|
+
// Capture is best-effort: a failure never breaks the response.
|
|
106
|
+
}
|
|
107
|
+
// A read's not found travels as a success status (see the worker);
|
|
108
|
+
// oRPC decodes an error from the status, so the 404 goes back on.
|
|
109
|
+
if (response.headers.has(SLOTFORM_NOT_FOUND_HEADER)) {
|
|
110
|
+
return new Response(response.body, {
|
|
111
|
+
status: 404,
|
|
112
|
+
statusText: "Not Found",
|
|
113
|
+
headers: response.headers,
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
return response;
|
|
117
|
+
},
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
const client = createORPCClient<RouterClient<TRouter>>(link);
|
|
121
|
+
|
|
122
|
+
// A later `createClient` call never overwrites the registered client; an
|
|
123
|
+
// explicit `registerApiClient` always does.
|
|
124
|
+
if (getRegisteredApiClient() === undefined) {
|
|
125
|
+
registerApiClient(client);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
return client;
|
|
129
|
+
}
|
package/src/error.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { ORPCError as ApiError } from "@orpc/server";
|