@dusted/anqst 0.1.2 → 1.0.0

package/dist/src/parser.js

@@ -55,26 +55,168 @@ function parseMemberKindFromAnQstType(typeNode) {
     if (!typeName.startsWith("AnQst."))
         return null;
     const kind = typeName.slice("AnQst.".length);
-    if (!["Call", "Slot", "Emitter", "Output", "Input"].includes(kind))
+    if (!["Call", "Slot", "Emitter", "Output", "Input", "DropTarget", "HoverTarget"].includes(kind))
         return null;
     if (kind === "Emitter")
         return { kind, payload: null };
     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", "DropTarget", "HoverTarget"].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" || kind === "HoverTarget") ? (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;
+}
+const DEFAULT_HOVER_RATE_HZ = 60;
+const DEFAULT_HOVER_THROTTLE_MS = Math.round(1000 / DEFAULT_HOVER_RATE_HZ);
+function resolveHoverThrottleMs(source, serviceName, memberName, kind, configTypeNode, warnings, memberLoc) {
+    if (kind !== "HoverTarget")
+        return 0;
+    if (!configTypeNode)
+        return DEFAULT_HOVER_THROTTLE_MS;
+    if (!typescript_1.default.isTypeLiteralNode(configTypeNode)) {
+        throw new errors_1.VerifyError(`HoverTarget config for '${memberName}' must be an inline object literal type.`, locFromNode(source, configTypeNode));
+    }
+    let maxRateHz = null;
+    const memberPath = `${serviceName}.${memberName}`;
+    for (const prop of configTypeNode.members) {
+        if (!typescript_1.default.isPropertySignature(prop) || !prop.name) {
+            throw new errors_1.VerifyError(`HoverTarget config for '${memberName}' only supports named properties.`, locFromNode(source, prop));
+        }
+        if (!typescript_1.default.isIdentifier(prop.name)) {
+            throw new errors_1.VerifyError(`HoverTarget config for '${memberName}' only supports identifier keys.`, locFromNode(source, prop.name));
+        }
+        const key = prop.name.text;
+        if (!prop.type) {
+            throw new errors_1.VerifyError(`HoverTarget config key '${key}' in '${memberName}' must declare a numeric literal value.`, locFromNode(source, prop));
+        }
+        if (key !== "maxRateHz") {
+            warnings.push({
+                severity: "warn",
+                message: `Unknown HoverTarget config key '${key}' ignored for '${memberPath}'.`,
+                loc: locFromNode(source, prop.name),
+                memberPath
+            });
+            continue;
+        }
+        const numericValue = parseNumericLiteralType(prop.type);
+        if (numericValue === null || !Number.isFinite(numericValue)) {
+            throw new errors_1.VerifyError(`HoverTarget config key '${key}' in '${memberName}' must be a numeric literal >= 0.`, locFromNode(source, prop.type));
+        }
+        if (numericValue < 0) {
+            throw new errors_1.VerifyError(`HoverTarget config key '${key}' in '${memberName}' must be >= 0.`, locFromNode(source, prop.type));
+        }
+        maxRateHz = numericValue;
+    }
+    if (maxRateHz === null)
+        return DEFAULT_HOVER_THROTTLE_MS;
+    return maxRateHz === 0 ? 0 : Math.round(1000 / maxRateHz);
+}
+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") {
+        if (parsed.kind === "Input" || parsed.kind === "Output" || parsed.kind === "DropTarget" || parsed.kind === "HoverTarget") {
             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 +229,14 @@ 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,
+            hoverThrottleMs: 0,
             loc: locFromNode(source, member)
         };
     }
@@ -100,20 +245,24 @@ 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") {
+        if (parsed.kind !== "Input" && parsed.kind !== "Output" && parsed.kind !== "DropTarget" && parsed.kind !== "HoverTarget") {
             throw new errors_1.VerifyError(`${parsed.kind} must be declared as method, not property.`, locFromNode(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));
+        const hoverThrottleMs = resolveHoverThrottleMs(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,
+            hoverThrottleMs,
             loc: locFromNode(source, member)
         };
     }
@@ -228,12 +377,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 +407,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,12 +1,13 @@
 {
   "name": "@dusted/anqst",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "description": "Opinionated backend generator for webapps.",
   "keywords": [
     "nodejs",
     "qt",
     "angular",
-    "webapp"
+    "webapp",
+    "apigenerator"
   ],
   "homepage": "https://github.com/DusteDdk/AnQst#readme",
   "bugs": {