@dusted/anqst 0.1.0

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

@@ -0,0 +1,217 @@
+/**
+ * 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": { "WidgetSpec": "MyUserMgmtWidget.AnQstSpec.d.ts" }
+ */
+
+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 }
+
+    /**
+     * 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",
+    }
+
+}
+