@justscale/typescript 0.1.1

package/dist/compiler/errors.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Custom error codes for the process compiler (TSPxxxx range).
+ */
+import ts from 'typescript';
+/**
+ * Custom error codes for process compilation.
+ * Range: TSP1000-TSP9999
+ */
+export declare const ProcessErrorCode: {
+    /**
+     * TSP1001: Non-serializable await result must use `using` declaration.
+     *
+     * Process state is serialized to storage when suspended. Awaited values
+     * from service calls (like `orders.get(Order.ref(id))`) return non-serializable
+     * objects that must be rehydrated on resume.
+     *
+     * Wrong: `const order = await orders.get(Order.ref(id))`
+     * Right: `using order = await orders.get(Order.ref(id))`
+     */
+    readonly NonSerializableConst: 1001;
+    /**
+     * TSP1002: Signal must be awaited inside process handler.
+     *
+     * The `signal()` primitive creates a suspension point and must be awaited.
+     *
+     * Wrong: `signal(orders.complete)`
+     * Right: `await signal(orders.complete)`
+     */
+    readonly SignalNotAwaited: 1002;
+    /**
+     * TSP1003: Invalid race pattern - switch must use `await race()`.
+     *
+     * The race pattern requires a specific structure with switch/case.
+     */
+    readonly InvalidRacePattern: 1003;
+    /**
+     * TSP1004: Process handler must be an async function.
+     */
+    readonly HandlerNotAsync: 1004;
+    /**
+     * TSP1005: Cannot use non-deterministic operations in process handler.
+     *
+     * Operations like `Date.now()`, `Math.random()`, or `crypto.randomUUID()`
+     * produce different results on replay and break determinism.
+     */
+    readonly NonDeterministicOperation: 1005;
+    /**
+     * TSP1006: Signal/delay must be used directly, not stored in a variable.
+     *
+     * The compiler transforms signal() and delay() calls at compile time.
+     * Storing them in variables breaks this transformation.
+     *
+     * Wrong: `const s = signal(orders.paid); await s;`
+     * Right: `await signal(orders.paid)`
+     *
+     * Wrong: `const d = delay.minutes(5); await d;`
+     * Right: `await delay.minutes(5)`
+     */
+    readonly SignalStoredInVariable: 1006;
+    /**
+     * TSP1007: Cannot use try-catch around suspension points.
+     *
+     * Process suspensions serialize state to storage. Exceptions cannot be
+     * caught across suspension boundaries because the try-catch context is
+     * lost when the process resumes from storage.
+     *
+     * Wrong: `try { await signal(orders.paid) } catch (e) { ... }`
+     * Right: Use race() with a timeout or handle errors in the signaling service.
+     */
+    readonly TryCatchWithSuspension: 1007;
+    /**
+     * TSP1008: Cannot use nested async functions with suspension points.
+     *
+     * Suspension points must be directly in the process handler, not in
+     * nested async functions or callbacks. The compiler cannot track
+     * suspensions through nested function boundaries.
+     *
+     * Wrong: `const fn = async () => { await signal(...) }; await fn()`
+     * Right: Use await signal() directly in the handler.
+     */
+    readonly NestedAsyncWithSuspension: 1008;
+    /**
+     * TSP1009: Cannot use Promise.all/Promise.race with signals.
+     *
+     * Process primitives like signal() and delay() must be awaited directly
+     * or used in a race() switch pattern. Promise combinators bypass the
+     * compiler's suspension tracking.
+     *
+     * Wrong: `await Promise.all([signal(a), signal(b)])`
+     * Right: Use sequential awaits or the race() switch pattern.
+     */
+    readonly PromiseCombinatorWithSignal: 1009;
+    /**
+     * TSP1010: For-in loops with suspension points are not supported.
+     *
+     * For-in iteration over object keys cannot be made durable because
+     * property enumeration order is not guaranteed to be stable.
+     * Convert to Object.keys() with a for-of loop or while loop.
+     *
+     * Wrong: `for (const key in obj) { await signal(...) }`
+     * Right: `for (const key of Object.keys(obj)) { await signal(...) }`
+     */
+    readonly ForInWithSuspension: 1010;
+    /**
+     * TSP1011: Inner function escapes handler scope.
+     *
+     * Inner functions with suspension points must be called directly within
+     * the handler. Returning them, storing them in arrays, or passing them
+     * to other functions prevents the compiler from inlining.
+     *
+     * Wrong: `const fn = async () => { await signal(...) }; return fn`
+     * Right: `const fn = async () => { await signal(...) }; await fn()`
+     */
+    readonly FunctionEscapesScope: 1011;
+    /**
+     * TSP1012: Parallel functions cannot have parameters.
+     *
+     * Functions used in signal.all() cannot have parameters because they
+     * are executed in parallel without specific arguments.
+     *
+     * Wrong: `signal.all([async (x) => { await signal(...) }])`
+     * Right: `signal.all([async () => { await signal(...) }])`
+     */
+    readonly ParallelFunctionWithParams: 1012;
+    /**
+     * TSP1013: While-loop condition contains a suspension point.
+     *
+     * The compiler cannot suspend inside a while-loop condition because
+     * the condition is re-evaluated on each iteration before the loop body.
+     * Move the suspension into the loop body with an explicit break.
+     *
+     * Wrong: `while (await signal(svc.hasMore)) { ... }`
+     * Right: `while (true) { if (!await signal(svc.hasMore)) break; ... }`
+     */
+    readonly WhileConditionSuspension: 1013;
+    /**
+     * TSP1014: Do-while loops with suspension points are not supported.
+     *
+     * The compiler does not yet support do-while loops containing
+     * suspension points. Convert to a while(true) loop with a break.
+     *
+     * Wrong: `do { await signal(svc.event) } while (condition)`
+     * Right: `while (true) { await signal(svc.event); if (!condition) break }`
+     */
+    readonly DoWhileWithSuspension: 1014;
+    /**
+     * TSP1015: Classic for loops with suspension points are not supported.
+     *
+     * The compiler cannot make classic for(;;) loops durable because the
+     * incrementor and condition expressions would need to be re-evaluated
+     * on resume. Convert to a while loop with explicit counter management.
+     *
+     * Wrong: `for (let i = 0; i < n; i++) { await signal(...) }`
+     * Right: `let i = 0; while (i < n) { await signal(...); i++ }`
+     */
+    readonly ForWithSuspension: 1015;
+    /**
+     * TSP2001: Recursion depth cannot be determined statically.
+     *
+     * The compiler must inline inner functions into the parent state machine.
+     * Recursive calls require static bounds to prevent infinite expansion.
+     *
+     * Wrong: `function recurse(n) { if (n > 0) await recurse(n - 1) }`
+     * Right: Use a while loop or bounded recursion with a constant limit.
+     */
+    readonly RecursionDepthUnknown: 2001;
+    /**
+     * TSP2002: Mutual recursion detected.
+     *
+     * Two or more functions that call each other cannot be inlined into
+     * a state machine. The compiler cannot determine the call order.
+     *
+     * Wrong: `function a() { b() } function b() { a() }`
+     * Right: Restructure to use a single function or loop.
+     */
+    readonly MutualRecursion: 2002;
+    /**
+     * TSP2003: Maximum inlining depth exceeded.
+     *
+     * The nested function call depth exceeds the maximum allowed for
+     * inlining (default: 10 levels). This prevents state machine explosion.
+     */
+    readonly MaxInliningDepthExceeded: 2003;
+    /**
+     * TSP3001: Invalid durable iterator (missing ORDER BY).
+     *
+     * Repository queries used in for-of loops must have an ORDER BY clause
+     * with at least one unique column for keyset pagination to work.
+     */
+    readonly InvalidDurableIterator: 3001;
+    /**
+     * TSP3002: Non-serializable cursor type.
+     *
+     * Durable iterators must produce serializable cursors (strings, numbers,
+     * or objects of primitives). Complex objects cannot be persisted.
+     */
+    readonly NonSerializableCursor: 3002;
+    /**
+     * TSP3003: Yield in non-generator handler.
+     *
+     * The `yield` expression can only be used in async generator handlers
+     * declared with `async *handler()`. Regular async handlers cannot yield.
+     *
+     * Wrong: `async handler() { yield event }`
+     * Right: `async *handler() { yield event }`
+     */
+    readonly YieldInNonGenerator: 3003;
+    /**
+     * TSP3004: Throw statement not allowed in process handler.
+     *
+     * Process handlers should return error results instead of throwing.
+     * Thrown exceptions break the durable execution model.
+     *
+     * Wrong: `throw new Error('failed')`
+     * Right: `return { status: 'error', message: 'failed' }`
+     */
+    readonly ThrowNotAllowed: 3004;
+    /**
+     * TSP3005: signal.all() with empty array literal.
+     *
+     * Parallel blocks must have at least one branch.
+     *
+     * Wrong: `await signal.all([])`
+     * Right: `await signal.all([svc.a, svc.b])`
+     */
+    readonly EmptyParallelBlock: 3005;
+    /**
+     * TSP3006: scope() exceeded item limit.
+     *
+     * The scope() function limits the number of entities to prevent
+     * state explosion. Default limit is 1000 items.
+     */
+    readonly ScopeItemLimitExceeded: 3006;
+    /**
+     * TSP3007: Scope handler cannot yield.
+     *
+     * Handlers inside scope() cannot use yield. To emit events from
+     * scoped processing, use a process reference with subprocess.
+     *
+     * Wrong: `scope(items, async (item) => { yield item })`
+     * Right: `scope(processRef, items)`
+     */
+    readonly ScopeHandlerCannotYield: 3007;
+    /**
+     * TSP3008: Duplicate entity in scope.
+     *
+     * Each entity in a scope() call must have a unique identity.
+     * Duplicate IDs would create conflicting execution paths.
+     */
+    readonly DuplicateEntityInScope: 3008;
+    /**
+     * TSP3009: Nested scope collision.
+     *
+     * Cannot nest scope() calls with the same model type. This would
+     * create ambiguous identity paths.
+     */
+    readonly NestedScopeCollision: 3009;
+    /**
+     * TSP3010: Race switch has no valid branches.
+     *
+     * A race switch must have at least one signal or delay branch.
+     * An empty switch would suspend indefinitely.
+     *
+     * Wrong: `const r = race(); switch (true) { default: break }`
+     * Right: `const r = race(); switch (true) { case signal(r, svc.a): ... }`
+     */
+    readonly EmptyRace: 3010;
+    /**
+     * TSP3011: Invalid scope() arguments.
+     *
+     * scope() requires at least 2 arguments in one of these forms:
+     * - scope(signal, entities)
+     * - scope(entities, handler)
+     * - scope(entities, idFn, handler)
+     */
+    readonly InvalidScopeArguments: 3011;
+    /**
+     * TSP3012: signal.all / signal.settled / stream inside race switch.
+     *
+     * These combinators are not yet supported as case expressions in a race
+     * switch. Use them as standalone awaits outside of a race, or use plain
+     * signal(r, ...) / delay(r, ...) branches.
+     *
+     * Wrong: `case signal.all(r, [svc.a, svc.b]):`
+     * Right: `case signal(r, svc.a):` or `const result = await signal.all([svc.a, svc.b])`
+     */
+    readonly RaceCombinatorNotSupported: 3012;
+    /**
+     * TSP3013: Variable shadowing in process handler.
+     *
+     * Process state is serialized to a flat `state.vars.{name}` namespace.
+     * Block-scoped redeclarations (`const x = 1; { const x = 99 }`) collapse
+     * onto the same storage slot — the inner binding silently overwrites the
+     * outer, breaking lexical scope semantics. Function-parameter shadowing
+     * is fine (parameters live in their own activation record); this error
+     * is only for declarations that share a flat scope with the outer binding.
+     *
+     * Wrong: `const x = 1; { const x = 99; ... }`
+     * Right: `const x = 1; { const innerX = 99; ... }`
+     */
+    readonly ShadowedHandlerLocal: 3013;
+};
+export type ProcessErrorCode = (typeof ProcessErrorCode)[keyof typeof ProcessErrorCode];
+/**
+ * Create a process-specific diagnostic.
+ */
+export declare function createProcessDiagnostic(code: ProcessErrorCode, node: ts.Node, ...args: string[]): ts.Diagnostic;
+/**
+ * Format error code for display.
+ */
+export declare function formatErrorCode(code: ProcessErrorCode): string;
+/**
+ * Check if a diagnostic is a process-specific error.
+ */
+export declare function isProcessDiagnostic(diagnostic: ts.Diagnostic): boolean;
+/**
+ * Get the process error code from a diagnostic.
+ */
+export declare function getProcessErrorCode(diagnostic: ts.Diagnostic): ProcessErrorCode | null;
+/**
+ * Collector for process diagnostics during compilation.
+ */
+export declare class DiagnosticCollector {
+    private diagnostics;
+    add(code: ProcessErrorCode, node: ts.Node, ...args: string[]): void;
+    getAll(): ts.Diagnostic[];
+    hasErrors(): boolean;
+    clear(): void;
+}
+/**
+ * Filter TS2850 diagnostics for `using exports` declarations in process files.
+ * TS2850 fires because the exports object doesn't have Symbol.dispose, but
+ * our compiler handles disposal separately - this diagnostic is noise.
+ */
+export declare function filterUsingExportsDiagnostics(diagnostics: ts.Diagnostic[]): ts.Diagnostic[];
+//# sourceMappingURL=errors.d.ts.map

package/dist/compiler/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/compiler/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;;;;;OASG;;IAGH;;;;;;;OAOG;;IAGH;;;;OAIG;;IAGH;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;;;;OAWG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;;;;OAYG;;CAEK,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAiIxF;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,EAAE,CAAC,UAAU,CAoBf;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAGtF;AAGD;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,WAAW,CAAuB;IAE1C,GAAG,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAInE,MAAM,IAAI,EAAE,CAAC,UAAU,EAAE;IAIzB,SAAS,IAAI,OAAO;IAIpB,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,EAAE,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,CAqB3F"}