@dusted/anqst 0.1.2 → 0.1.3

package/dist/src/parser.js

@@ -62,19 +62,116 @@ function parseMemberKindFromAnQstType(typeNode) {
     const arg = typeNode.typeArguments?.[0];
     return { kind, payload: arg ? arg.getText() : null };
 }
-function parseServiceMember(source, member) {
+const DEFAULT_MEMBER_TIMEOUT_MS = 120000;
+const MAX_MEMBER_TIMEOUT_MS = 2147483647;
+function parseMemberKindWithConfig(typeNode) {
+    if (!typescript_1.default.isTypeReferenceNode(typeNode))
+        return null;
+    const typeName = qNameToText(typeNode.typeName);
+    if (!typeName.startsWith("AnQst."))
+        return null;
+    const kind = typeName.slice("AnQst.".length);
+    if (!["Call", "Slot", "Emitter", "Output", "Input"].includes(kind))
+        return null;
+    const typeArgs = typeNode.typeArguments ?? [];
+    if (kind === "Emitter") {
+        return {
+            kind,
+            payload: null,
+            configTypeNode: typeArgs[0] ?? null
+        };
+    }
+    return {
+        kind,
+        payload: typeArgs[0] ? typeArgs[0].getText() : null,
+        configTypeNode: kind === "Call" ? (typeArgs[1] ?? null) : null
+    };
+}
+function parseNumericLiteralType(node) {
+    if (!typescript_1.default.isLiteralTypeNode(node))
+        return null;
+    if (typescript_1.default.isNumericLiteral(node.literal)) {
+        return Number(node.literal.text);
+    }
+    if (typescript_1.default.isPrefixUnaryExpression(node.literal)
+        && node.literal.operator === typescript_1.default.SyntaxKind.MinusToken
+        && typescript_1.default.isNumericLiteral(node.literal.operand)) {
+        return -Number(node.literal.operand.text);
+    }
+    return null;
+}
+function resolveMemberTimeoutMs(source, serviceName, memberName, kind, configTypeNode, warnings, memberLoc) {
+    if (kind !== "Call")
+        return DEFAULT_MEMBER_TIMEOUT_MS;
+    if (!configTypeNode)
+        return DEFAULT_MEMBER_TIMEOUT_MS;
+    if (!typescript_1.default.isTypeLiteralNode(configTypeNode)) {
+        throw new errors_1.VerifyError(`${kind} config for '${memberName}' must be an inline object literal type.`, locFromNode(source, configTypeNode));
+    }
+    let timeoutSeconds = null;
+    let timeoutMilliseconds = null;
+    const memberPath = `${serviceName}.${memberName}`;
+    for (const prop of configTypeNode.members) {
+        if (!typescript_1.default.isPropertySignature(prop) || !prop.name) {
+            throw new errors_1.VerifyError(`${kind} config for '${memberName}' only supports named properties.`, locFromNode(source, prop));
+        }
+        if (!typescript_1.default.isIdentifier(prop.name)) {
+            throw new errors_1.VerifyError(`${kind} config for '${memberName}' only supports identifier keys.`, locFromNode(source, prop.name));
+        }
+        const key = prop.name.text;
+        if (!prop.type) {
+            throw new errors_1.VerifyError(`${kind} config key '${key}' in '${memberName}' must declare a numeric literal value.`, locFromNode(source, prop));
+        }
+        if (key !== "timeoutSeconds" && key !== "timeoutMilliseconds") {
+            warnings.push({
+                severity: "warn",
+                message: `Unknown ${kind} config key '${key}' ignored for '${memberPath}'.`,
+                loc: locFromNode(source, prop.name),
+                memberPath
+            });
+            continue;
+        }
+        const numericValue = parseNumericLiteralType(prop.type);
+        if (numericValue === null || !Number.isInteger(numericValue)) {
+            throw new errors_1.VerifyError(`${kind} config key '${key}' in '${memberName}' must be an integer literal >= 0.`, locFromNode(source, prop.type));
+        }
+        if (numericValue < 0) {
+            throw new errors_1.VerifyError(`${kind} config key '${key}' in '${memberName}' must be >= 0.`, locFromNode(source, prop.type));
+        }
+        if (key === "timeoutSeconds")
+            timeoutSeconds = numericValue;
+        if (key === "timeoutMilliseconds")
+            timeoutMilliseconds = numericValue;
+    }
+    if (timeoutSeconds !== null && timeoutMilliseconds !== null) {
+        throw new errors_1.VerifyError(`${kind} config for '${memberName}' must specify only one of 'timeoutSeconds' or 'timeoutMilliseconds'.`, memberLoc);
+    }
+    const effectiveMs = timeoutMilliseconds !== null
+        ? timeoutMilliseconds
+        : timeoutSeconds !== null
+            ? timeoutSeconds * 1000
+            : DEFAULT_MEMBER_TIMEOUT_MS;
+    if (effectiveMs > MAX_MEMBER_TIMEOUT_MS) {
+        throw new errors_1.VerifyError(`${kind} timeout for '${memberName}' exceeds max supported value (${MAX_MEMBER_TIMEOUT_MS} ms).`, memberLoc);
+    }
+    return effectiveMs;
+}
+function parseServiceMember(source, serviceName, member, warnings) {
     if (typescript_1.default.isMethodSignature(member)) {
         if (member.questionToken)
             throw new errors_1.VerifyError("Optional service methods are not allowed.", locFromNode(source, member));
         const returnType = member.type;
         if (!returnType)
             throw new errors_1.VerifyError("Service method must declare return type.", locFromNode(source, member));
-        const parsed = parseMemberKindFromAnQstType(returnType);
+        const parsed = parseMemberKindWithConfig(returnType);
         if (!parsed)
             throw new errors_1.VerifyError(`Unsupported service method return type '${returnType.getText()}'.`, locFromNode(source, member));
         if (parsed.kind === "Input" || parsed.kind === "Output") {
             throw new errors_1.VerifyError(`${parsed.kind} must be declared as property, not method.`, locFromNode(source, member));
         }
+        if (parsed.kind === "Emitter" && parsed.configTypeNode !== null) {
+            throw new errors_1.VerifyError(`Emitter '${member.name.getText(source)}' does not support config parameters; use plain AnQst.Emitter.`, locFromNode(source, parsed.configTypeNode));
+        }
         if (!member.name || !typescript_1.default.isIdentifier(member.name)) {
             throw new errors_1.VerifyError("Only identifier service method names are supported.", locFromNode(source, member));
         }
@@ -87,11 +184,13 @@ function parseServiceMember(source, member) {
                 throw new errors_1.VerifyError("Service parameters must declare type.", locFromNode(source, param));
             return { name: param.name.text, typeText: param.type.getText() };
         });
+        const timeoutMs = resolveMemberTimeoutMs(source, serviceName, member.name.text, parsed.kind, parsed.configTypeNode, warnings, locFromNode(source, member));
         return {
             kind: parsed.kind,
             name: member.name.text,
             payloadTypeText: parsed.payload,
             parameters,
+            timeoutMs,
             loc: locFromNode(source, member)
         };
     }
@@ -100,7 +199,7 @@ function parseServiceMember(source, member) {
             throw new errors_1.VerifyError("Service property must declare type.", locFromNode(source, member));
         if (member.questionToken)
             throw new errors_1.VerifyError("Optional service properties are not allowed.", locFromNode(source, member));
-        const parsed = parseMemberKindFromAnQstType(member.type);
+        const parsed = parseMemberKindWithConfig(member.type);
         if (!parsed)
             throw new errors_1.VerifyError(`Unsupported service property type '${member.type.getText()}'.`, locFromNode(source, member));
         if (parsed.kind !== "Input" && parsed.kind !== "Output") {
@@ -109,11 +208,13 @@ function parseServiceMember(source, member) {
         if (!member.name || !typescript_1.default.isIdentifier(member.name)) {
             throw new errors_1.VerifyError("Only identifier service property names are supported.", locFromNode(source, member));
         }
+        const timeoutMs = resolveMemberTimeoutMs(source, serviceName, member.name.text, parsed.kind, parsed.configTypeNode, warnings, locFromNode(source, member));
         return {
             kind: parsed.kind,
             name: member.name.text,
             payloadTypeText: parsed.payload,
             parameters: [],
+            timeoutMs,
             loc: locFromNode(source, member)
         };
     }
@@ -228,12 +329,13 @@ function parseSpecFileAst(specFilePath) {
         throw new errors_1.VerifyError("Namespace body must be a block.", locFromNode(source, ns));
     const services = [];
     const namespaceTypeDecls = [];
+    const warnings = [];
     let supportsDevelopmentModeTransport = false;
     for (const stmt of ns.body.statements) {
         if (typescript_1.default.isInterfaceDeclaration(stmt)) {
             const baseType = serviceBaseType(stmt);
             if (baseType !== null) {
-                const members = stmt.members.map((member) => parseServiceMember(source, member));
+                const members = stmt.members.map((member) => parseServiceMember(source, stmt.name.text, member, warnings));
                 if (baseType === "AngularHTTPBaseServerClass") {
                     supportsDevelopmentModeTransport = true;
                 }
@@ -257,7 +359,8 @@ function parseSpecFileAst(specFilePath) {
         namespaceTypeDecls,
         importedTypeDecls: importInfo.importedTypeDecls,
         importedTypeSymbols: importInfo.importedTypeSymbols,
-        specImports: importInfo.specImports
+        specImports: importInfo.specImports,
+        warnings
     };
 }
 function parseSpecFile(specFilePath) {

package/dist/src/verify.js

@@ -194,9 +194,14 @@ function verifySpecSemantics(spec) {
         reachableGeneratedTypes: reachable.size,
         serviceCount: spec.services.length
     };
+    const warnings = [...spec.warnings];
+    const warningSummary = warnings.length === 0
+        ? ""
+        : `\nWarnings:\n${warnings.map((w) => `    [warn] ${w.loc.file}:${w.loc.line}:${w.loc.column} ${w.memberPath} - ${w.message}`).join("\n")}`;
     return {
         stats,
-        message: `AnQst spec valid:\n    ${stats.namespaceDeclaredTypes} types.\n    ${stats.serviceCount} services.`
+        message: `AnQst spec valid:\n    ${stats.namespaceDeclaredTypes} types.\n    ${stats.serviceCount} services.${warningSummary}`,
+        warnings
     };
 }
 function verifySpec(spec) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dusted/anqst",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Opinionated backend generator for webapps.",
   "keywords": [
     "nodejs",

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

@@ -10,20 +10,20 @@
  * - 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"
+ * 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.
@@ -44,6 +44,7 @@ export namespace AnQst {
      */
     interface AngularHTTPBaseServerClass extends Service { }
 
+    type CallConfig = { timeoutSeconds: number } | { timeoutMilliseconds: number } | {};
 
     /**
      * Declare non-blocking service method `MethodName`(`MethodArguments`): Promise<`MethodReturnType`>.
@@ -52,27 +53,38 @@ export namespace AnQst {
      * - 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.
+     *   - 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> { dummy: T }
+    interface Call<T, Config extends CallConfig = {}> { dummy: T; config?: Config }
 
-    /**
-     * Declare blocking service method onSlot.`MethodName`( handler(`MethodArguments`):`MethodReturnType` ): void
+    /**
+     * 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.
+     *   - 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.
+     * - Generated C++ Slot methods do not expose `ok/error` out parameters.
+     * - Default Slot timeout is 1000ms.
      * Note: One active handler, calling will replace existing and is valid and allowed.
      * @example
      * // AnQst spec:
@@ -95,6 +107,7 @@ export namespace AnQst {
      *   - 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;
@@ -144,20 +157,20 @@ export namespace AnQst {
 
     /**
      * 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)",
@@ -195,13 +208,13 @@ export namespace AnQst {
 
     /**
      * 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 {
@@ -213,5 +226,24 @@ export namespace AnQst {
         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."
+    }
+
 }