Skip to content

Commit ce78d12

Browse files
committed
fix(toilscript): ambient .d.ts declarations for the streams/daemon decorators + types
Increment 1 added the decorators to the compiler but not the ambient TypeScript declarations in std/assembly/toilscript.d.ts, so user code writing @daemon/@stream/etc. did not type-check or get editor IntelliSense. Added (matching the existing @rest/@data/@Remote pattern): - @daemon (class), @scheduled(spec) (method factory), @stream (+ StreamOptions/StreamScope overloads), and the lifecycle-hook method decorators @connect/@message/@close/@disconnect/@channel. - Ambient handler types: StreamInbound, StreamOutbound, StreamConnectionEvent, StreamPacket, StreamChannelMessage (per streams-docs/03 sections 3.1-3.6). StreamInbound.user() (the @auth bridge) is intentionally omitted: AuthUser is compiler-injected per project, not ambient, so referencing it here would not resolve in the dts type-check; deferred to the stream/auth integration (Phase 4). Full build incl. the dts type-check is green.
1 parent 309ce9f commit ce78d12

1 file changed

Lines changed: 95 additions & 0 deletions

File tree

std/assembly/toilscript.d.ts

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,101 @@ declare function auth(target: Object, propertyKey: string | symbol, descriptor:
8585
/** Declare the authenticated-user type (`@user class User { ... }`); enables `AuthService.getUser()`. */
8686
declare function user(target: Function): void;
8787

88+
// --- L4 daemon (@daemon / @scheduled) + streams (@stream + lifecycle hooks),
89+
// handled natively by the compiler; typed here so editors accept the bare forms ---
90+
91+
/** Marks the single L4 daemon class: instantiated once on the global cold box,
92+
* its instance fields preserved for the box lifetime. At most one `@daemon` per
93+
* project. May declare a zero-arg `onStart(): void`, run once at boot. Cold
94+
* artifact only (a `@daemon` is a compile error in the hot/request build). */
95+
declare function daemon(target: Function): void;
96+
97+
/** Declares a `@daemon` method as a scheduled task fired on each due tick. `spec`
98+
* is an interval (`"30s"` / `"5m"` / `"1h"` / `"1d"`) or a 5-field cron string
99+
* (e.g. `"15 9 * * 1-5"`, weekdays 9:15). The handler must be `(): void` (no parameters, no return). */
100+
declare function scheduled(spec: string): (target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>) => void;
101+
102+
/** Stream placement scope for `@stream({ scope })`: `Regional` (0, L2) or
103+
* `Continental` (1, L3). Values match the runtime stream codec. */
104+
declare enum StreamScope { Regional, Continental }
105+
106+
/** Optional `@stream` config object. Set `message` to a `@data` class to receive
107+
* decoded packets; omit it for the raw-bytes default (`StreamPacket`). */
108+
interface StreamOptions {
109+
scope?: StreamScope;
110+
message?: Function;
111+
maxFrameBytes?: i32;
112+
ingressRingBytes?: i32;
113+
}
114+
115+
/** Marks a class as a stream protocol handler (runs on L2/L3 nodes). Its
116+
* `@connect`/`@message`/`@close`/`@disconnect`/`@channel` methods are the
117+
* lifecycle hooks. A project that uses `@stream` may NOT declare any `@service`
118+
* or `@remote` anywhere (compiler-enforced). Hot/stream artifact only. */
119+
declare function stream(target: Function): void;
120+
declare function stream(options: StreamOptions): (target: Function) => void;
121+
122+
/** Stream lifecycle-hook method decorators on a `@stream` class. `@connect` runs
123+
* on open (returns `StreamOutbound`); `@message` handles an inbound packet;
124+
* `@close` is a graceful close; `@disconnect` is an abrupt transport loss;
125+
* `@channel` receives an opt-in fanned-out channel message. */
126+
declare function connect(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
127+
declare function message(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
128+
declare function close(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
129+
declare function disconnect(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
130+
declare function channel(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
131+
132+
// Stream handler argument/return types. Ambient (like the bignum natives below):
133+
// the compiler/runtime provides the real classes; declared here so `@stream`
134+
// handler signatures type-check in any editor.
135+
136+
/** The connection-open context passed to `@connect`. Read-only. */
137+
declare class StreamInbound {
138+
get connectionId(): u64;
139+
get streamName(): string;
140+
get remoteIp(): string;
141+
get path(): string;
142+
header(name: string): string;
143+
}
144+
145+
/** The accept/reject + optional first-frame decision returned by
146+
* `@connect` / `@message`. */
147+
declare class StreamOutbound {
148+
static accept(): StreamOutbound;
149+
static reply(body: Uint8Array): StreamOutbound;
150+
static reject(reason: u16): StreamOutbound;
151+
static empty(): StreamOutbound;
152+
}
153+
154+
/** The close context passed to `@close` (a graceful or host-initiated close,
155+
* distinct from `@disconnect`). */
156+
declare class StreamConnectionEvent {
157+
get connectionId(): u64;
158+
get reason(): u16;
159+
get durationMs(): u64;
160+
}
161+
162+
/** The default (raw-bytes) `@message` parameter: a thin view over the host
163+
* ingress ring. The ring slot is reused after the hook returns, so copy via
164+
* `bytes()` to retain. */
165+
declare class StreamPacket {
166+
get connectionId(): u64;
167+
get length(): i32;
168+
bytes(): Uint8Array;
169+
at(i: i32): u8;
170+
}
171+
172+
/** The fanned-out channel message passed to `@channel`: the channel name plus
173+
* the raw published bytes (no decode). */
174+
declare class StreamChannelMessage {
175+
get connectionId(): u64;
176+
get channelHash(): u32;
177+
get channelName(): string;
178+
get length(): i32;
179+
bytes(): Uint8Array;
180+
at(i: i32): u8;
181+
}
182+
88183
// --- ToilDB (@database / @collection + the @query/@action/... function kinds),
89184
// handled natively by the compiler; typed here so editors accept the bare forms ---
90185

0 commit comments

Comments
 (0)