@supacloud/compiler 0.33.0 → 0.35.0

package/dist/cli.js

@@ -2380,6 +2380,15 @@ function renderClient(graph, options) {
         const command = route.command === undefined ? undefined : commandByClassName.get(route.command);
         const procedureKind = route.method === "GET" || route.method === "HEAD" ? "query" : "mutation";
         const idempotencyMode = command?.idempotency ?? "none";
+        const procedureMetadata = {
+          key: `${controller.className}.${route.handler}`,
+          method: route.method,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          kind: procedureKind,
+          idempotency: idempotencyMode
+        };
         allProcedures.push({
           method: route.method,
           path: fullPath,
@@ -2391,7 +2400,7 @@ function renderClient(graph, options) {
           idempotency: idempotencyMode
         });
         routeMethods.push(`
-    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}),`);
+    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}, ${JSON.stringify(procedureMetadata)}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -2425,6 +2434,19 @@ function renderClient(graph, options) {
     'export type ProcedureKind = "query" | "mutation";',
     'export type IdempotencyMode = "required" | "none";',
     "",
+    "export interface ProcedureMetadata<",
+    "  Kind extends ProcedureKind = ProcedureKind,",
+    "  Idempotency extends IdempotencyMode = IdempotencyMode,",
+    "> {",
+    "  key: string;",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  kind: Kind;",
+    "  idempotency: Idempotency;",
+    "}",
+    "",
     "export interface ProcedureExecutionOptions {",
     "  /** Reuse the same key when retrying an uncertain mutation. */",
     "  idempotencyKey?: string;",
@@ -2450,14 +2472,24 @@ function renderClient(graph, options) {
     '  Idempotency extends IdempotencyMode = "none",',
     "> = (...args: ProcedureArgs<Options, Idempotency>) => Promise<ProcedureResult<Result>>;",
     "",
+    "export type QueryableProcedure<",
+    "  Options extends ClientRequestOptions,",
+    "  Result,",
+    "  Idempotency extends IdempotencyMode,",
+    "  Kind extends ProcedureKind,",
+    "> = ProcedureCall<Options, Result, Idempotency> & {",
+    "  readonly __supacloudProcedure: ProcedureMetadata<Kind, Idempotency>;",
+    "  readonly __supacloudInput?: Options;",
+    "};",
+    "",
     "export type ProcedureMember<",
     "  Options extends ClientRequestOptions,",
     "  Result,",
     "  Kind extends ProcedureKind,",
     "  Idempotency extends IdempotencyMode,",
     '> = Kind extends "query"',
-    "  ? { query: ProcedureCall<Options, Result, Idempotency> }",
-    "  : { mutate: ProcedureCall<Options, Result, Idempotency> };",
+    '  ? { query: QueryableProcedure<Options, Result, Idempotency, "query"> }',
+    '  : { mutate: QueryableProcedure<Options, Result, Idempotency, "mutation"> };',
     "",
     'export type ApiClientErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED";',
     "",
@@ -2477,7 +2509,7 @@ function renderClient(graph, options) {
     "  readonly path: string;",
     "  readonly status: number;",
     "  readonly requestId: string | undefined;",
-    "  /** Undeclared HTTP response for explicit inspection; excluded from JSON serialization. */",
+    "  /** HTTP response for inspection; successful response bodies may already be consumed. */",
     "  readonly response: Response | undefined;",
     "  constructor(message: string, details: ApiClientErrorDetails) {",
     "    super(message);",
@@ -2824,25 +2856,27 @@ function renderClient(graph, options) {
     "    const declaredSchema = responseSchemas ? selectResponseSchema(response.status, responseSchemas) : undefined;",
     "    const failure = (code: ApiClientErrorCode, message: string) => new ApiClientError(message, {",
     '      code, method, path, status: response.status, requestId: response.headers.get("x-request-id"),',
-    '      ...(code === "API_HTTP_ERROR" ? { response } : {}),',
+    "      response,",
     "    });",
     "    if (!response.ok && declaredSchema === undefined) {",
     '      throw failure("API_HTTP_ERROR", `API request failed: ${method} ${path} -> ${response.status}`);',
     "    }",
+    "    // Preserve the original HTTP error response if a declared error body fails validation.",
+    "    const bodyResponse = response.ok ? response : response.clone();",
     '    const contentType = response.headers?.get("content-type") ?? "";',
     "    let value: unknown;",
     "    if ([204, 205, 304].includes(response.status)) {",
     "      value = undefined;",
     '    } else if (contentType.includes("application/json") || contentType.includes("+json")) {',
-    "      const responseText = await response.text();",
+    "      const responseText = await bodyResponse.text();",
     "      try { value = JSON.parse(responseText); }",
     '      catch { throw failure("API_RESPONSE_INVALID", "Response is not valid JSON"); }',
     '    } else if (responseKind === "binary" || contentType.includes("application/octet-stream")) {',
-    "      value = await response.arrayBuffer();",
+    "      value = await bodyResponse.arrayBuffer();",
     '    } else if (responseKind === "stream") {',
-    "      value = response.body;",
+    "      value = bodyResponse.body;",
     "    } else {",
-    "      value = await response.text();",
+    "      value = await bodyResponse.text();",
     "    }",
     "    if (!responseSchemas) return decode ? decode(value) : value;",
     "    if (declaredSchema === undefined) {",
@@ -2869,9 +2903,10 @@ function renderClient(graph, options) {
     "  ): ClientRequestOptions {",
     "    const headers = { ...(options.headers as Record<string, string> | undefined) };",
     "    if (execution?.idempotencyKey !== undefined) {",
-    "      if (!/^[A-Za-z0-9._:-]{1,512}$/.test(execution.idempotencyKey)) {",
+    '      if (typeof execution.idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(execution.idempotencyKey)) {',
     '        throw new TypeError("idempotencyKey must contain only safe header characters and be at most 512 characters");',
     "      }",
+    '      for (const key of Object.keys(headers)) if (key.toLowerCase() === "idempotency-key") delete headers[key];',
     '      headers["idempotency-key"] = execution.idempotencyKey;',
     "    }",
     '    if (idempotency === "required" && !hasHeader(headers, "idempotency-key")) {',
@@ -2885,17 +2920,17 @@ function renderClient(graph, options) {
     '    return Object.hasOwn(value, "idempotencyKey") || Object.hasOwn(value, "signal");',
     "  }",
     "",
-    `  function makeProcedure<Options extends ClientRequestOptions, Result = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, idempotency: Idempotency = "none" as Idempotency): ProcedureCall<Options, Result, Idempotency> {`,
+    `  function makeProcedure<Options extends ClientRequestOptions, Result = never, Idempotency extends IdempotencyMode = "none", Kind extends ProcedureKind = ProcedureKind>(metadata: ProcedureMetadata<Kind, Idempotency>, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): QueryableProcedure<Options, Result, Idempotency, Kind> {`,
     "    const procedure = async (first?: Options | ProcedureExecutionOptions, second?: ProcedureExecutionOptions): Promise<unknown> => {",
     "      const execution = second ?? (isProcedureExecution(first) ? first : undefined);",
     "      const input = (execution === first ? undefined : first) ?? {};",
-    "      const requestOptions = withProcedureExecution(input as ClientRequestOptions, execution, idempotency);",
-    "      return request(method, path, requestOptions, undefined, responseSchemas, responseKind, raw, execution);",
+    "      const requestOptions = withProcedureExecution(input as ClientRequestOptions, execution, metadata.idempotency);",
+    "      return request(metadata.method, metadata.path, requestOptions, undefined, responseSchemas, responseKind, raw, execution);",
     "    };",
-    "    return procedure as ProcedureCall<Options, Result, Idempotency>;",
+    "    return Object.assign(procedure, { __supacloudProcedure: Object.freeze(metadata) }) as QueryableProcedure<Options, Result, Idempotency, Kind>;",
     "  }",
     "",
-    `  function makeRoute<Options extends ClientRequestOptions, Result = never, Kind extends ProcedureKind = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, kind?: Kind, idempotency: Idempotency = "none" as Idempotency): RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency> {`,
+    `  function makeRoute<Options extends ClientRequestOptions, Result = never, Kind extends ProcedureKind = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, kind?: Kind, idempotency: Idempotency = "none" as Idempotency, metadata?: ProcedureMetadata<Kind, Idempotency>): RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency> {`,
     "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
     "    function route(options: Options): Promise<Result>;",
     "    function route(options?: Options): Promise<unknown>;",
@@ -2903,8 +2938,8 @@ function renderClient(graph, options) {
     "      const requestOptions = options ?? {};",
     "      return request(method, path, requestOptions, decode, responseSchemas, responseKind, raw);",
     "    }",
-    '    if (kind === "query") Object.assign(route, { query: makeProcedure<Options, Result, Idempotency>(method, path, responseSchemas, responseKind, raw, idempotency) });',
-    '    if (kind === "mutation") Object.assign(route, { mutate: makeProcedure<Options, Result, Idempotency>(method, path, responseSchemas, responseKind, raw, idempotency) });',
+    '    if (kind === "query" && metadata) Object.assign(route, { query: makeProcedure<Options, Result, Idempotency, "query">(metadata as ProcedureMetadata<"query", Idempotency>, responseSchemas, responseKind, raw) });',
+    '    if (kind === "mutation" && metadata) Object.assign(route, { mutate: makeProcedure<Options, Result, Idempotency, "mutation">(metadata as ProcedureMetadata<"mutation", Idempotency>, responseSchemas, responseKind, raw) });',
     "    return route as RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency>;",
     "  }",
     "",

package/dist/index.js

@@ -2379,6 +2379,15 @@ function renderClient(graph, options) {
         const command = route.command === undefined ? undefined : commandByClassName.get(route.command);
         const procedureKind = route.method === "GET" || route.method === "HEAD" ? "query" : "mutation";
         const idempotencyMode = command?.idempotency ?? "none";
+        const procedureMetadata = {
+          key: `${controller.className}.${route.handler}`,
+          method: route.method,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          kind: procedureKind,
+          idempotency: idempotencyMode
+        };
         allProcedures.push({
           method: route.method,
           path: fullPath,
@@ -2390,7 +2399,7 @@ function renderClient(graph, options) {
           idempotency: idempotencyMode
         });
         routeMethods.push(`
-    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}),`);
+    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}, ${JSON.stringify(procedureMetadata)}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -2424,6 +2433,19 @@ function renderClient(graph, options) {
     'export type ProcedureKind = "query" | "mutation";',
     'export type IdempotencyMode = "required" | "none";',
     "",
+    "export interface ProcedureMetadata<",
+    "  Kind extends ProcedureKind = ProcedureKind,",
+    "  Idempotency extends IdempotencyMode = IdempotencyMode,",
+    "> {",
+    "  key: string;",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  kind: Kind;",
+    "  idempotency: Idempotency;",
+    "}",
+    "",
     "export interface ProcedureExecutionOptions {",
     "  /** Reuse the same key when retrying an uncertain mutation. */",
     "  idempotencyKey?: string;",
@@ -2449,14 +2471,24 @@ function renderClient(graph, options) {
     '  Idempotency extends IdempotencyMode = "none",',
     "> = (...args: ProcedureArgs<Options, Idempotency>) => Promise<ProcedureResult<Result>>;",
     "",
+    "export type QueryableProcedure<",
+    "  Options extends ClientRequestOptions,",
+    "  Result,",
+    "  Idempotency extends IdempotencyMode,",
+    "  Kind extends ProcedureKind,",
+    "> = ProcedureCall<Options, Result, Idempotency> & {",
+    "  readonly __supacloudProcedure: ProcedureMetadata<Kind, Idempotency>;",
+    "  readonly __supacloudInput?: Options;",
+    "};",
+    "",
     "export type ProcedureMember<",
     "  Options extends ClientRequestOptions,",
     "  Result,",
     "  Kind extends ProcedureKind,",
     "  Idempotency extends IdempotencyMode,",
     '> = Kind extends "query"',
-    "  ? { query: ProcedureCall<Options, Result, Idempotency> }",
-    "  : { mutate: ProcedureCall<Options, Result, Idempotency> };",
+    '  ? { query: QueryableProcedure<Options, Result, Idempotency, "query"> }',
+    '  : { mutate: QueryableProcedure<Options, Result, Idempotency, "mutation"> };',
     "",
     'export type ApiClientErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED";',
     "",
@@ -2476,7 +2508,7 @@ function renderClient(graph, options) {
     "  readonly path: string;",
     "  readonly status: number;",
     "  readonly requestId: string | undefined;",
-    "  /** Undeclared HTTP response for explicit inspection; excluded from JSON serialization. */",
+    "  /** HTTP response for inspection; successful response bodies may already be consumed. */",
     "  readonly response: Response | undefined;",
     "  constructor(message: string, details: ApiClientErrorDetails) {",
     "    super(message);",
@@ -2823,25 +2855,27 @@ function renderClient(graph, options) {
     "    const declaredSchema = responseSchemas ? selectResponseSchema(response.status, responseSchemas) : undefined;",
     "    const failure = (code: ApiClientErrorCode, message: string) => new ApiClientError(message, {",
     '      code, method, path, status: response.status, requestId: response.headers.get("x-request-id"),',
-    '      ...(code === "API_HTTP_ERROR" ? { response } : {}),',
+    "      response,",
     "    });",
     "    if (!response.ok && declaredSchema === undefined) {",
     '      throw failure("API_HTTP_ERROR", `API request failed: ${method} ${path} -> ${response.status}`);',
     "    }",
+    "    // Preserve the original HTTP error response if a declared error body fails validation.",
+    "    const bodyResponse = response.ok ? response : response.clone();",
     '    const contentType = response.headers?.get("content-type") ?? "";',
     "    let value: unknown;",
     "    if ([204, 205, 304].includes(response.status)) {",
     "      value = undefined;",
     '    } else if (contentType.includes("application/json") || contentType.includes("+json")) {',
-    "      const responseText = await response.text();",
+    "      const responseText = await bodyResponse.text();",
     "      try { value = JSON.parse(responseText); }",
     '      catch { throw failure("API_RESPONSE_INVALID", "Response is not valid JSON"); }',
     '    } else if (responseKind === "binary" || contentType.includes("application/octet-stream")) {',
-    "      value = await response.arrayBuffer();",
+    "      value = await bodyResponse.arrayBuffer();",
     '    } else if (responseKind === "stream") {',
-    "      value = response.body;",
+    "      value = bodyResponse.body;",
     "    } else {",
-    "      value = await response.text();",
+    "      value = await bodyResponse.text();",
     "    }",
     "    if (!responseSchemas) return decode ? decode(value) : value;",
     "    if (declaredSchema === undefined) {",
@@ -2868,9 +2902,10 @@ function renderClient(graph, options) {
     "  ): ClientRequestOptions {",
     "    const headers = { ...(options.headers as Record<string, string> | undefined) };",
     "    if (execution?.idempotencyKey !== undefined) {",
-    "      if (!/^[A-Za-z0-9._:-]{1,512}$/.test(execution.idempotencyKey)) {",
+    '      if (typeof execution.idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(execution.idempotencyKey)) {',
     '        throw new TypeError("idempotencyKey must contain only safe header characters and be at most 512 characters");',
     "      }",
+    '      for (const key of Object.keys(headers)) if (key.toLowerCase() === "idempotency-key") delete headers[key];',
     '      headers["idempotency-key"] = execution.idempotencyKey;',
     "    }",
     '    if (idempotency === "required" && !hasHeader(headers, "idempotency-key")) {',
@@ -2884,17 +2919,17 @@ function renderClient(graph, options) {
     '    return Object.hasOwn(value, "idempotencyKey") || Object.hasOwn(value, "signal");',
     "  }",
     "",
-    `  function makeProcedure<Options extends ClientRequestOptions, Result = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, idempotency: Idempotency = "none" as Idempotency): ProcedureCall<Options, Result, Idempotency> {`,
+    `  function makeProcedure<Options extends ClientRequestOptions, Result = never, Idempotency extends IdempotencyMode = "none", Kind extends ProcedureKind = ProcedureKind>(metadata: ProcedureMetadata<Kind, Idempotency>, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): QueryableProcedure<Options, Result, Idempotency, Kind> {`,
     "    const procedure = async (first?: Options | ProcedureExecutionOptions, second?: ProcedureExecutionOptions): Promise<unknown> => {",
     "      const execution = second ?? (isProcedureExecution(first) ? first : undefined);",
     "      const input = (execution === first ? undefined : first) ?? {};",
-    "      const requestOptions = withProcedureExecution(input as ClientRequestOptions, execution, idempotency);",
-    "      return request(method, path, requestOptions, undefined, responseSchemas, responseKind, raw, execution);",
+    "      const requestOptions = withProcedureExecution(input as ClientRequestOptions, execution, metadata.idempotency);",
+    "      return request(metadata.method, metadata.path, requestOptions, undefined, responseSchemas, responseKind, raw, execution);",
     "    };",
-    "    return procedure as ProcedureCall<Options, Result, Idempotency>;",
+    "    return Object.assign(procedure, { __supacloudProcedure: Object.freeze(metadata) }) as QueryableProcedure<Options, Result, Idempotency, Kind>;",
     "  }",
     "",
-    `  function makeRoute<Options extends ClientRequestOptions, Result = never, Kind extends ProcedureKind = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, kind?: Kind, idempotency: Idempotency = "none" as Idempotency): RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency> {`,
+    `  function makeRoute<Options extends ClientRequestOptions, Result = never, Kind extends ProcedureKind = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, kind?: Kind, idempotency: Idempotency = "none" as Idempotency, metadata?: ProcedureMetadata<Kind, Idempotency>): RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency> {`,
     "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
     "    function route(options: Options): Promise<Result>;",
     "    function route(options?: Options): Promise<unknown>;",
@@ -2902,8 +2937,8 @@ function renderClient(graph, options) {
     "      const requestOptions = options ?? {};",
     "      return request(method, path, requestOptions, decode, responseSchemas, responseKind, raw);",
     "    }",
-    '    if (kind === "query") Object.assign(route, { query: makeProcedure<Options, Result, Idempotency>(method, path, responseSchemas, responseKind, raw, idempotency) });',
-    '    if (kind === "mutation") Object.assign(route, { mutate: makeProcedure<Options, Result, Idempotency>(method, path, responseSchemas, responseKind, raw, idempotency) });',
+    '    if (kind === "query" && metadata) Object.assign(route, { query: makeProcedure<Options, Result, Idempotency, "query">(metadata as ProcedureMetadata<"query", Idempotency>, responseSchemas, responseKind, raw) });',
+    '    if (kind === "mutation" && metadata) Object.assign(route, { mutate: makeProcedure<Options, Result, Idempotency, "mutation">(metadata as ProcedureMetadata<"mutation", Idempotency>, responseSchemas, responseKind, raw) });',
     "    return route as RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency>;",
     "  }",
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",