@dusted/anqst 0.1.2 → 1.0.0

package/spec/AnQst-Spec-DSL.d.ts

@@ -1,217 +1,327 @@
-/**
- * AnQst-Spec Language - Canonical source of truth for the language.
- *
- * @remarks
- * - DSL for Widget generation, transported as TypeScript definition.
- * - For AnQSt Widget Specifications only.
- * - Exactly one toplevel namespace must be declared: It names the Widget.
- * - Service interfaces are optional. Namespace-local type declarations are valid generation roots.
- * - Imported/external types are generation-relevant when transitively reachable from namespace declarations.
- * - This is not an input file to the generator, it is the description of the language that describes the widget.
- *   Not for use by TypeScript application implementation.
- * @example
+/**
+ * AnQst-Spec Language - Canonical source of truth for the language.
+ *
+ * @remarks
+ * - DSL for Widget generation, transported as TypeScript definition.
+ * - For AnQSt Widget Specifications only.
+ * - Exactly one toplevel namespace must be declared: It names the Widget.
+ * - Service interfaces are optional. Namespace-local type declarations are valid generation roots.
+ * - Imported/external types are generation-relevant when transitively reachable from namespace declarations.
+ * - This is not an input file to the generator, it is the description of the language that describes the widget.
+ *   Not for use by TypeScript application implementation.
+ * @example
  * package.json:
  * - "AnQst": "./AnQst/MyUserMgmtWidget.settings.json"
- */
-
-export namespace AnQst {
-
-    /**
-     * Declare service `InterfaceName`
-     * 
-     * @remarks
-     * Multiple allowed.
-     * Affords developers of advanced widgets the ability to create domain-informed categories.
-     * - Duplicate method declarations with identical parameter lists are invalid in normative AnQst-Spec input.
-     * 
-     * @example
-     * export interface UserService extends Widget.Service { }
-     * // Generates UserService.
-     */
-    interface Service { }
-
-    /**
-     * Declare service `InterfaceName` as development-mode capable transport service.
-     *
-     * @remarks
-     * - Extends the same method/property semantics as `AnQst.Service`.
-     * - Signals to the generator/runtime that this widget should emit dual-transport bridge support
-     *   (Qt WebChannel + HTTP/WebSocket development bridge).
-     * - Existing generated service APIs remain unchanged.
-     *
-     * @example
-     * export interface UserService extends AnQst.AngularHTTPBaseServerClass { }
-     */
-    interface AngularHTTPBaseServerClass extends Service { }
-
-
-    /**
-     * Declare non-blocking service method `MethodName`(`MethodArguments`): Promise<`MethodReturnType`>.
-     * @remarks
-     * - **Widget** -> Parent
-     * - Flow:
-     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
-     *   - Widget: Returns Promise<`MethodReturnType`>.
-     *   - Parent: Registered `MethodReturnType` `MethodName`_Handler(`MethodArguments`) is called.
-     *   - Parent: Handler returns result.
-     *   - Widget: Promise resolves with result.
-     * @example
-     * // AnQst spec:
-     * getUserById(userId: string): AnQst.Call<User>
-     * //Angular app:
-     * const user: User = await this.userService.getUserById("abc");
-    */
-    interface Call<T> { dummy: T }
-
+ */
+
+export namespace AnQst {
+
+    /**
+     * Declare service `InterfaceName`
+     * 
+     * @remarks
+     * Multiple allowed.
+     * Affords developers of advanced widgets the ability to create domain-informed categories.
+     * - Duplicate method declarations with identical parameter lists are invalid in normative AnQst-Spec input.
+     * 
+     * @example
+     * export interface UserService extends Widget.Service { }
+     * // Generates UserService.
+     */
+    interface Service { }
+
+    /**
+     * Declare service `InterfaceName` as development-mode capable transport service.
+     *
+     * @remarks
+     * - Extends the same method/property semantics as `AnQst.Service`.
+     * - Signals to the generator/runtime that this widget should emit dual-transport bridge support
+     *   (Qt WebChannel + HTTP/WebSocket development bridge).
+     * - Existing generated service APIs remain unchanged.
+     *
+     * @example
+     * export interface UserService extends AnQst.AngularHTTPBaseServerClass { }
+     */
+    interface AngularHTTPBaseServerClass extends Service { }
+
+    type CallConfig = { timeoutSeconds: number } | { timeoutMilliseconds: number } | {};
+
+    /**
+     * Declare non-blocking service method `MethodName`(`MethodArguments`): Promise<`MethodReturnType`>.
+     * @remarks
+     * - **Widget** -> Parent
+     * - Flow:
+     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
+     *   - Widget: Returns Promise<`MethodReturnType`>.
+     *   - Parent: Registered callback receives args and returns `T` synchronously.
+     *   - Widget: Promise resolves with payload `T` or rejects with plain error object.
+     * - Optional config supports timeout tuning:
+     *   - `AnQst.Call<T, { timeoutSeconds: N }>`
+     *   - `AnQst.Call<T, { timeoutMilliseconds: N }>`
+     * - Exactly one timeout key is allowed. Value must be integer >= 0.
+     * - Default timeout is 120s. `0` means wait forever.
+     * @example
+     * // AnQst spec:
+     * getUserById(userId: string): AnQst.Call<User>
+     * //Angular app:
+     * const user: User = await this.userService.getUserById("abc");
+    */
+    interface Call<T, Config extends CallConfig = {}> { dummy: T; config?: Config }
+
     /**
      * Declare blocking service method onSlot.`MethodName`( handler(`MethodArguments`):`MethodReturnType` ): void
-     * @remarks
-     * - **Parent** -> Widget
-     * - Impl note: Autogenerated stub handler queues until handler is set (set method calls spools queue through handler)
-     * - Flow:
-     *   - Parent: Call to generated widget method `MethodName`(`MethodArguments`).
-     *   - Widget: Registered handler(`MethodArguments`): `MethodReturnType` is called.
-     *   - Widget: Handler returns result.
-     *   - Parent: `MethodName` call returns with result.
-     * Note: One active handler, calling will replace existing and is valid and allowed.
-     * @example
-     * // AnQst spec:
-     * getUsernameSubstring(from: number, to:number ): AnQst.Slot<string>
-     * //Angular app:
-     * this.userService.onSlot.getUsername( provider );
-     * //Parent:
-     * auto currentFormUsername = userMgmt.getUsername();
-    */
-    interface Slot<T> { dummy: T }
-
-
-
-    /**
-     * Declare message emission method `MethodName`(`MethodArguments`): void
-     * @remarks
-     * - **Widget** -> ?Parent
-     * True Qt signal semantics (Message is emitted, no return path, no registration requirement)
-     * - Flow:
-     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
-     *   - Widget: Returns void.
-     *   - Parent: Might have something connected to the signal, might not.
-     * @example
-     * // AnQst spec:
-     * complain(whine: string): AnQst.Emitter;
-     * //Angular app:
-     * this.userService.complain("Why won't you LISTEN!");
-    */
-    interface Emitter { }
-
-
-    /**
-     * Declare reactive `PropertyName`:`OutputType` and set.`PropertyName`(arg: `OutputType`)
-     * @remarks
-     * - **Parent** -> Widget
-     * True Angular signal semantics (Property updates, signal emits, no return path, no registration requirement)
-     * - Flow:
-     *   - Parent: Sets generated widget property `PropertyName`.
-     *   - Widget: Service updates readonly property `PropertyName` and emits signal.
-     * @example
-     * // AnQst spec:
-     * activeUsers: AnQst.Output<number>;
-     * //Angular app template:
-     * <p>{{ userService.activeUsers() }}</p>
-     * //Parent:
-     * int users = userMgmt.activeUsers;
-     * userMgmt.activeUsers = 99;
-     */
-    interface Output<OutputType> {}
-
-
-    /**
-     * Declare Input bindable set.`PropertyName`(input:`InputType`): void and `PropertyName`:`InputType`
-     * @remarks
-     * - **Widget** -> Parent
-     * - Convenience method, for symmetry with Output.
-     * - Flow:
-     *   - Widget: Calls service set.`PropertyName`(`InputType`) to publish current value.
-     *   - Parent: Mirrored generated widget property `PropertyName` is updated and emits change notification.
-     * @example
-     * // AnQst spec:
-     * currentUsername: AnQst.Input<string>;
-     * //Angular app template:
-     * <input type="text" placeholder="Your Name Here" (input)="userService.set.currentUsername(($event.target as HTMLInputElement).value)" />
-     * //Parent:
-     * QString userName = userMgmt.currentUsername;
-     */
-    interface Input<InputType> {}
-
-    /**
-     * AnQst-Spec type mapping overview and control.
-     * 
-     * @remarks
-     * Any Type that be mapped between TypeScript and Qt, C++ standard types or
-     *     Plain Old Data (POD) types (in that order of preference) will be mapped by default.
-     * 
-     * Canonical mapping directive namespace is AnQst.Type.<type>.
-     * To express advisory mapping preference, use AnQst.Type.<type>.
-     * Advisory means generator SHOULD honor it, but MAY fall back to inferred/default mapping and emit diagnostic.
-     * Array forms are equivalent: T[] == Array<T>, and AnQst.Type.X[] == Array<AnQst.Type.X>.
-     * 
-     * TypeScript definitions+classes and C++ structs are generated for each
-     *     structured TypeScript type ( type = {...} or interface { ... } )
-     *     referenced in an AnQst spec.
-     * 
-     */
-    enum Type {
-        object = "JavaScript Object <-> QVariantMap (JSON.stringify/parse semantics)",
-        json  = "JavaScript Object <-> QJsonObject (JSON.stringify/parse semantics)",
-        string = "JavaScript String <-> QString",
-        stringArray = "JavaScript String[] <-> QStringList",
-        number = "JavaScript Number <-> double",
-        qint64 = "JavaScript BigInt <-> qint64 (Default, for symmetry, same as direct use of <BigInt> which is allowed.)",
-        quint64 = "JavaScript BigInt <-> quint64",
-        qint32 = "JavaScript Number <-> qint32",
-        quint32 = "JavaScript Number <-> quint32",
-        qint16 = "JavaScript Number <-> qint16",
-        quint16 = "JavaScript Number <-> quint16",
-        qint8 = "JavaScript Number <-> qint8",
-        quint8 = "JavaScript Number <-> quint8",
-        int32 = "JavaScript Number <-> int32_t",
-        uint32 = "JavaScript Number <-> uint32_t",
-        int16 = "JavaScript Number <-> int16_t",
-        uint16 = "JavaScript Number <-> uint16_t",
-        int8 = "JavaScript Number <-> int8_t",
-        uint8 = "JavaScript Number <-> uint8_t",
-        buffer = "JavaScript ArrayBuffer <-> QByteArray (Default, for symmetry, same as direct use of <ArrayBuffer> which is allowed.)",
-        blob = "JavaScript ArrayBuffer <-> QByteArray",
-        typedArray = "JavaScript TypedArray <-> QByteArray",
-        uint8Array = "JavaScript Uint8Array <-> QByteArray",
-        int8Array = "JavaScript Int8Array <-> QByteArray",
-        uint16Array = "JavaScript Uint16Array <-> QByteArray",
-        int16Array = "JavaScript Int16Array <-> QByteArray",
-        uint32Array = "JavaScript Uint32Array <-> QByteArray",
-        int32Array = "JavaScript Int32Array <-> QByteArray",
-        float32Array = "JavaScript Float32Array <-> QByteArray",
-        float64Array = "JavaScript Float64Array <-> QByteArray",
-    }
-
-
-    /**
-     * These are explicitly forbidden argument/return types.
-     * 
-     * @remarks
-     * - They may not be referenced in AnQst specs or imported types.
-     * - Service methods cannot accept them as arguments
-     * - Service methods cannot return them.
-     * - Service properties of their type cannot be declared.
-     * 
-     * - For Objects/Maps/Sets use AnQst.Type.<Type> instead.
-     */
-    export enum ForbiddenType {
-        Function = "Passing callbacks across the boundary is not allowed.",
-        Class = "Passing classes across the boundary is not allowed.",
-        Type = "Passing types across the boundary is not allowed.",
-        Promise = "Passing Promises across the boundary is not allowed",
-        Callable = "Passing Callable objects across the boundary is not allowed",
-        any = "Passing 'any' type across the boundary is not allowed",
-    }
-
-}
-
+     * @remarks
+     * - **Parent** -> Widget
+     * - Impl note: Autogenerated stub handler queues until handler is set (set method calls spools queue through handler)
+     * - Flow:
+     *   - Parent: Call to generated widget method `MethodName`(`MethodArguments`).
+     *   - Widget: Registered handler(`MethodArguments`) is called.
+     *   - Widget: Handler return forms:
+     *      - `T` -> success payload
+     *      - `Promise<T>` -> awaited, success payload on resolve
+     *      - `Error` -> failure
+     *      - throw -> failure
+     *      - rejected promise -> failure
+     *   - Parent: `MethodName` call returns with result.
+     * - Default Slot timeout is 1000ms.
+     * Note: One active handler, calling will replace existing and is valid and allowed.
+     * @example
+     * // AnQst spec:
+     * getUsernameSubstring(from: number, to:number ): AnQst.Slot<string>
+     * //Angular app:
+     * this.userService.onSlot.getUsername( provider );
+     * //Parent:
+     * auto currentFormUsername = userMgmt.getUsername();
+    */
+    interface Slot<T> { dummy: T }
+
+
+
+    /**
+     * Declare message emission method `MethodName`(`MethodArguments`): void
+     * @remarks
+     * - **Widget** -> ?Parent
+     * True Qt signal semantics (Message is emitted, no return path, no registration requirement)
+     * - Flow:
+     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
+     *   - Widget: Returns void.
+     *   - Parent: Might have something connected to the signal, might not.
+     * - If no listener is connected, event is dropped.
+     * @example
+     * // AnQst spec:
+     * complain(whine: string): AnQst.Emitter;
+     * //Angular app:
+     * this.userService.complain("Why won't you LISTEN!");
+    */
+    interface Emitter { }
+
+
+    /**
+     * Declare reactive `PropertyName`:`OutputType` and set.`PropertyName`(arg: `OutputType`)
+     * @remarks
+     * - **Parent** -> Widget
+     * True Angular signal semantics (Property updates, signal emits, no return path, no registration requirement)
+     * - Flow:
+     *   - Parent: Sets generated widget property `PropertyName`.
+     *   - Widget: Service updates readonly property `PropertyName` and emits signal.
+     * @example
+     * // AnQst spec:
+     * activeUsers: AnQst.Output<number>;
+     * //Angular app template:
+     * <p>{{ userService.activeUsers() }}</p>
+     * //Parent:
+     * int users = userMgmt.activeUsers;
+     * userMgmt.activeUsers = 99;
+     */
+    interface Output<OutputType> {}
+
+
+    /**
+     * Declare Input bindable set.`PropertyName`(input:`InputType`): void and `PropertyName`:`InputType`
+     * @remarks
+     * - **Widget** -> Parent
+     * - Convenience method, for symmetry with Output.
+     * - Flow:
+     *   - Widget: Calls service set.`PropertyName`(`InputType`) to publish current value.
+     *   - Parent: Mirrored generated widget property `PropertyName` is updated and emits change notification.
+     * @example
+     * // AnQst spec:
+     * currentUsername: AnQst.Input<string>;
+     * //Angular app template:
+     * <input type="text" placeholder="Your Name Here" (input)="userService.set.currentUsername(($event.target as HTMLInputElement).value)" />
+     * //Parent:
+     * QString userName = userMgmt.currentUsername;
+     */
+    interface Input<InputType> {}
+
+
+    /**
+     * Declare drop-target `PropertyName`:`PayloadType`
+     * @remarks
+     * - **Parent** -> Widget (framework-mediated)
+     * - True Angular signal semantics.
+     * - Flow:
+     *   - External: A Qt widget initiates a QDrag carrying QMimeData.
+     *   - Parent: AnQstWebHostBase intercepts the drop via event filter on the
+     *     embedded QWebEngineView's rendering surface.
+     *   - Parent: QMimeData for the accepted format is deserialized (JSON) into
+     *     the generated C++ struct and forwarded through the bridge.
+     *   - Widget: Service updates signal `PropertyName` with the deserialized
+     *     payload and drop coordinates. Angular components react via effect() / template binding.
+     * - MIME type is convention-derived: `application/anqst-dragdropevent_<ServiceName>-<TypeName>`.
+     * - The source QWidget must serialize the drag payload as JSON under the same MIME type.
+     * - Multiple DropTarget members per service are allowed (each accepting a different type).
+     * @example
+     * // AnQst spec:
+     * trackDropped: AnQst.DropTarget<Track>;
+     * // Angular app:
+     * effect(() => {
+     *   const drop = this.service.trackDropped();
+     *   if (drop !== null) { console.log(drop.payload, drop.x, drop.y); }
+     * });
+     */
+    interface DropTarget<T> { dummy: T }
+
+
+    /**
+     * Declare hover-target `PropertyName`:`PayloadType`
+     * @remarks
+     * - **Parent** -> Widget (framework-mediated)
+     * - True Angular signal semantics.
+     * - Flow:
+     *   - External: A Qt widget initiates a QDrag carrying QMimeData.
+     *   - Parent: AnQstWebHostBase intercepts drag-move events via event filter on the
+     *     embedded QWebEngineView's rendering surface. Events are throttled (trailing edge).
+     *   - Parent: Payload is deserialized once on DragEnter; subsequent DragMove events
+     *     forward only the updated position.
+     *   - Widget: Service updates signal `PropertyName` with the payload and current
+     *     coordinates. Signal becomes null on DragLeave.
+     * - Shares the same MIME type convention as DropTarget: `application/anqst-dragdropevent_<ServiceName>-<TypeName>`.
+     * - A HoverTarget without a corresponding DropTarget means "show previews but reject the drop".
+     * - Optional config supports throttle tuning:
+     *   - `AnQst.HoverTarget<T, { maxRateHz: N }>` — maximum rate of hover position updates
+     *     forwarded across the bridge, in hertz. The generator converts this to a millisecond
+     *     interval at build time (e.g. 60 Hz -> 17 ms, 10 Hz -> 100 ms).
+     *   - Default is 60 Hz (~17 ms throttle interval).
+     *   - `0` means no throttling: every QDragMoveEvent is forwarded immediately.
+     *   - There is no upper bound on the value.
+     * @example
+     * // AnQst spec (default 60 Hz throttle):
+     * trackHovering: AnQst.HoverTarget<Track>;
+     * // AnQst spec (custom 10 Hz throttle):
+     * trackHovering: AnQst.HoverTarget<Track, { maxRateHz: 10 }>;
+     * // AnQst spec (no throttling):
+     * trackHovering: AnQst.HoverTarget<Track, { maxRateHz: 0 }>;
+     * // Angular app:
+     * effect(() => {
+     *   const hover = this.service.trackHovering();
+     *   if (hover !== null) { highlight(document.elementFromPoint(hover.x, hover.y)); }
+     * });
+     */
+
+    /**
+     * Configuration for HoverTarget throttle behavior.
+     * @remarks
+     * - `maxRateHz` — Maximum rate in hertz at which hover position updates are forwarded.
+     *   - Default (omitted or `{}`): 60 Hz.
+     *   - `0`: No throttling; every QDragMoveEvent is forwarded.
+     *   - No upper bound.
+     *   - Value must be a numeric literal >= 0.
+     */
+    type HoverTargetConfig = { maxRateHz: number } | {};
+    interface HoverTarget<T, Config extends HoverTargetConfig = {}> { dummy: T; config?: Config }
+
+
+
+    /**
+     * AnQst-Spec type mapping overview and control.
+     *
+     * @remarks
+     * Any Type that be mapped between TypeScript and Qt, C++ standard types or
+     *     Plain Old Data (POD) types (in that order of preference) will be mapped by default.
+     *
+     * Canonical mapping directive namespace is AnQst.Type.<type>.
+     * To express advisory mapping preference, use AnQst.Type.<type>.
+     * Advisory means generator SHOULD honor it, but MAY fall back to inferred/default mapping and emit diagnostic.
+     * Array forms are equivalent: T[] == Array<T>, and AnQst.Type.X[] == Array<AnQst.Type.X>.
+     *
+     * TypeScript definitions+classes and C++ structs are generated for each
+     *     structured TypeScript type ( type = {...} or interface { ... } )
+     *     referenced in an AnQst spec.
+     *
+     */
+    enum Type {
+        object = "JavaScript Object <-> QVariantMap (JSON.stringify/parse semantics)",
+        json  = "JavaScript Object <-> QJsonObject (JSON.stringify/parse semantics)",
+        string = "JavaScript String <-> QString",
+        stringArray = "JavaScript String[] <-> QStringList",
+        number = "JavaScript Number <-> double",
+        qint64 = "JavaScript BigInt <-> qint64 (Default, for symmetry, same as direct use of <BigInt> which is allowed.)",
+        quint64 = "JavaScript BigInt <-> quint64",
+        qint32 = "JavaScript Number <-> qint32",
+        quint32 = "JavaScript Number <-> quint32",
+        qint16 = "JavaScript Number <-> qint16",
+        quint16 = "JavaScript Number <-> quint16",
+        qint8 = "JavaScript Number <-> qint8",
+        quint8 = "JavaScript Number <-> quint8",
+        int32 = "JavaScript Number <-> int32_t",
+        uint32 = "JavaScript Number <-> uint32_t",
+        int16 = "JavaScript Number <-> int16_t",
+        uint16 = "JavaScript Number <-> uint16_t",
+        int8 = "JavaScript Number <-> int8_t",
+        uint8 = "JavaScript Number <-> uint8_t",
+        buffer = "JavaScript ArrayBuffer <-> QByteArray (Default, for symmetry, same as direct use of <ArrayBuffer> which is allowed.)",
+        blob = "JavaScript ArrayBuffer <-> QByteArray",
+        typedArray = "JavaScript TypedArray <-> QByteArray",
+        uint8Array = "JavaScript Uint8Array <-> QByteArray",
+        int8Array = "JavaScript Int8Array <-> QByteArray",
+        uint16Array = "JavaScript Uint16Array <-> QByteArray",
+        int16Array = "JavaScript Int16Array <-> QByteArray",
+        uint32Array = "JavaScript Uint32Array <-> QByteArray",
+        int32Array = "JavaScript Int32Array <-> QByteArray",
+        float32Array = "JavaScript Float32Array <-> QByteArray",
+        float64Array = "JavaScript Float64Array <-> QByteArray",
+    }
+
+
+    /**
+     * These are explicitly forbidden argument/return types.
+     *
+     * @remarks
+     * - They may not be referenced in AnQst specs or imported types.
+     * - Service methods cannot accept them as arguments
+     * - Service methods cannot return them.
+     * - Service properties of their type cannot be declared.
+     *
+     * - For Objects/Maps/Sets use AnQst.Type.<Type> instead.
+     */
+    export enum ForbiddenType {
+        Function = "Passing callbacks across the boundary is not allowed.",
+        Class = "Passing classes across the boundary is not allowed.",
+        Type = "Passing types across the boundary is not allowed.",
+        Promise = "Passing Promises across the boundary is not allowed",
+        Callable = "Passing Callable objects across the boundary is not allowed",
+        any = "Passing 'any' type across the boundary is not allowed",
+    }
+
+    /**
+     * JS/TS Error instances can be returned, but they have special meaning.
+     *
+     * @remarks
+     * AnQst is opinionated, Errors are not for control flow. They are for signalling unrecoverable and unhandled circumstance.
+     * Use: To indicate unrecoverable program error/wrong use.
+     * Don't use: To communicate expected and/or ignorable/handable situations, define a domain-specific transport type instad.
+     * When else encountered: Unhandled Errors.
+     * Effect: The receiving end throws an exception with message `<service>.<member> emitted error: <WidgetStackTrace>`
+     * AnQst internal behavior:
+     * When AnQst type translation/mapping encounters a true Error object instance, the Error object is not transported, instead
+     * the sending AnQst code signals to the receiving AnQst code a message, and the receiving AnQst code throws a runtime exception on
+     * the call or callback site in the Parent.
+
+     */
+    export enum ExceptionalType {
+        Error = "AnQst will not transport an Error object, but will cause an exception to be thrown on reception site."
+    }
+
+}
+