sproutboat 0.8.0 → 0.9.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.
Files changed (16) hide show
  1. package/CHANGELOG.md +304 -0
  2. package/README.md +33 -1
  3. package/SURFACE.md +7 -4
  4. package/package.json +9 -5
  5. package/src/broker.ts +48 -5
  6. package/src/build.ts +8 -0
  7. package/src/compile.ts +42 -11
  8. package/src/dev.ts +2 -0
  9. package/src/main.ts +230 -2
  10. package/src/native-fetch-prelude.js +3 -3
  11. package/src/surface.ts +17 -3
  12. package/src/toolchain.ts +71 -0
  13. package/src/transport-broker.js +9 -0
  14. package/src/transport-embedded.js +4 -0
  15. package/src/types-gen.ts +90 -0
  16. package/types/sproutboat.d.ts +217 -0
package/types/sproutboat.d.ts ADDED
@@ -0,0 +1,217 @@
1
+ /**
2
+ * Ambient types for a Sproutboat handler.
3
+ *
4
+ * Shipped with the CLI rather than as a separate package, so the types always
5
+ * describe the runtime that the installed CLI compiles. `sproutboat types`
6
+ * generates a project's `sproutboat-env.d.ts`, which references this file and
7
+ * declares `env` with that project's bindings.
8
+ *
9
+ * Two things differ from Cloudflare Workers and are the reason these exist:
10
+ * `env` is a global rather than a parameter, so nothing is inferable from a
11
+ * signature, and every binding call is synchronous.
12
+ */
13
+
14
+ declare global {
15
+ // ---------------------------------------------------------------- KV
16
+
17
+ interface KVNamespace {
18
+ /** The stored string, or `null`. Synchronous: no `await`. */
19
+ get(key: string): string | null;
20
+ put(key: string, value: string): void;
21
+ delete(key: string): void;
22
+ /** Keys under `prefix` (all keys when omitted). */
23
+ list(prefix?: string): string[];
24
+ }
25
+
26
+ // ---------------------------------------------------------------- D1
27
+
28
+ interface D1Meta {
29
+ /** `INSERT` only. The autoincrement id of the row just written. */
30
+ last_row_id: number;
31
+ changes: number;
32
+ }
33
+
34
+ interface D1Result<T = Record<string, unknown>> {
35
+ results: T[];
36
+ success: boolean;
37
+ meta: D1Meta;
38
+ }
39
+
40
+ interface D1PreparedStatement {
41
+ /** Positional `?` parameters, in order. */
42
+ bind(...values: Array<string | number | boolean | null>): D1PreparedStatement;
43
+ all<T = Record<string, unknown>>(): D1Result<T>;
44
+ run(): D1Result;
45
+ /** The first row, or one column of it when named. `null` if there are none. */
46
+ first<T = Record<string, unknown>>(): T | null;
47
+ first<T = unknown>(column: string): T | null;
48
+ }
49
+
50
+ interface D1Database {
51
+ prepare(sql: string): D1PreparedStatement;
52
+ batch(statements: D1PreparedStatement[]): D1Result[];
53
+ /** Runs a whole script. Use this for multi-statement DDL. */
54
+ exec(sql: string): void;
55
+ }
56
+
57
+ // ---------------------------------------------------------------- R2
58
+
59
+ interface R2Object {
60
+ key: string;
61
+ size: number;
62
+ etag: string;
63
+ uploaded: string;
64
+ customMetadata?: Record<string, string>;
65
+ /**
66
+ * The object as a string. An object is held whole in memory on the way in
67
+ * and on the way out, so keep them small.
68
+ */
69
+ body: string;
70
+ }
71
+
72
+ type R2ObjectHead = Omit<R2Object, "body">;
73
+
74
+ interface R2Objects {
75
+ objects: R2ObjectHead[];
76
+ truncated: boolean;
77
+ cursor?: string;
78
+ }
79
+
80
+ interface R2PutOptions {
81
+ customMetadata?: Record<string, string>;
82
+ }
83
+
84
+ interface R2ListOptions {
85
+ prefix?: string;
86
+ limit?: number;
87
+ cursor?: string;
88
+ }
89
+
90
+ interface R2Bucket {
91
+ put(key: string, value: string, options?: R2PutOptions): void;
92
+ get(key: string): R2Object | null;
93
+ /** Metadata without the body. */
94
+ head(key: string): R2ObjectHead | null;
95
+ delete(key: string): void;
96
+ list(options?: R2ListOptions): R2Objects;
97
+ }
98
+
99
+ // ------------------------------------------------------------ Queues
100
+
101
+ interface QueueSendOptions {
102
+ delaySeconds?: number;
103
+ }
104
+
105
+ interface Queue<Body = unknown> {
106
+ /** Returns immediately. The batch reaches `queue()` out of band. */
107
+ send(body: Body, options?: QueueSendOptions): void;
108
+ sendBatch(messages: Array<{ body: Body }>): void;
109
+ }
110
+
111
+ interface QueueMessage<Body = unknown> {
112
+ id: string;
113
+ timestamp: number;
114
+ body: Body;
115
+ /** Mark as handled. Without this the message is redelivered. */
116
+ ack(): void;
117
+ /** Hand it back for another attempt. */
118
+ retry(): void;
119
+ }
120
+
121
+ interface MessageBatch<Body = unknown> {
122
+ queue: string;
123
+ messages: Array<QueueMessage<Body>>;
124
+ }
125
+
126
+ // --------------------------------------------------- Durable Objects
127
+
128
+ interface DurableObjectId {
129
+ toString(): string;
130
+ name?: string;
131
+ }
132
+
133
+ interface DurableObjectStub {
134
+ fetch(request: Request): Response;
135
+ }
136
+
137
+ interface DurableObjectNamespace {
138
+ idFromName(name: string): DurableObjectId;
139
+ idFromString(hex: string): DurableObjectId;
140
+ newUniqueId(): DurableObjectId;
141
+ get(id: DurableObjectId): DurableObjectStub;
142
+ }
143
+
144
+ interface DurableObjectStorage {
145
+ get<T = unknown>(key: string): T | undefined;
146
+ put<T>(key: string, value: T): void;
147
+ delete(key: string): void;
148
+ deleteAll(): void;
149
+ /** Stored values under `prefix`, keyed by storage key. */
150
+ list<T = unknown>(options?: { prefix?: string; limit?: number }): Map<string, T>;
151
+ /**
152
+ * At most one alarm is pending per object; a later `setAlarm` replaces it.
153
+ * The handler is the class's `alarm()` method.
154
+ */
155
+ setAlarm(scheduledTime: number): void;
156
+ getAlarm(): number | null;
157
+ deleteAlarm(): void;
158
+ }
159
+
160
+ interface DurableObjectState {
161
+ id: DurableObjectId;
162
+ /** Synchronous, like every other binding. */
163
+ storage: DurableObjectStorage;
164
+ }
165
+
166
+ // -------------------------------------------------- Analytics Engine
167
+
168
+ interface AnalyticsEngineDataPoint {
169
+ blobs?: string[];
170
+ doubles?: number[];
171
+ indexes?: string[];
172
+ }
173
+
174
+ interface AnalyticsEngineDataset {
175
+ writeDataPoint(event: AnalyticsEngineDataPoint): void;
176
+ query<T = unknown>(options?: { limit?: number }): { count: number; rows: T[] };
177
+ }
178
+
179
+ // ------------------------------------ Fetchers: services and assets
180
+
181
+ /** A service binding, and the shape of the static-asset binding. */
182
+ interface Fetcher {
183
+ fetch(request: Request): Response;
184
+ }
185
+
186
+ // --------------------------------------------------------- Handlers
187
+
188
+ interface ScheduledEvent {
189
+ /** The expression that fired, as written in `triggers.crons`. */
190
+ cron: string;
191
+ scheduledTime: number;
192
+ }
193
+
194
+ /**
195
+ * The default export.
196
+ *
197
+ * `fetch` takes only a request: `env` is a global, and there is no `ctx`, so
198
+ * there is no `ctx.waitUntil`. Use a queue for work that outlives a response.
199
+ */
200
+ interface SproutboatHandler<QueueBody = unknown> {
201
+ fetch(request: Request): Response | Promise<Response>;
202
+ scheduled?(event: ScheduledEvent): void | Promise<void>;
203
+ queue?(batch: MessageBatch<QueueBody>): void | Promise<void>;
204
+ }
205
+
206
+ /**
207
+ * What a Durable Object class implements. Declare it above the default
208
+ * export and name it in `durable_objects`.
209
+ */
210
+ interface DurableObject {
211
+ fetch(request: Request): Response | Promise<Response>;
212
+ /** Runs after `storage.setAlarm`, with no request in flight. */
213
+ alarm?(): void | Promise<void>;
214
+ }
215
+ }
216
+
217
+ export {};