@modelprofile.com/flexharness 12.0.0 → 12.1.1

package/ts_typedrequest/describe.ts

@@ -43,7 +43,7 @@ const withoutOmitted = (
   const target = referencedType(schema);
   if (target !== undefined) {
     const named = types[target];
-    return named !== undefined && holdsOmitted(named, omit, types, new Set([target]))
+    return named !== undefined && omittedIn(named, omit, types, new Set([target])).size > 0
       ? withoutOmitted(named, omit, types)
       : schema;
   }
@@ -63,22 +63,29 @@ const withoutOmitted = (
   return stripped;
 };
 
-/** Whether a schema has an omitted property, itself or through the schemas it composes or refers to. */
-const holdsOmitted = (
+/** The omitted properties a schema has, itself or through the schemas it composes or refers to. */
+const omittedIn = (
   schema: TFlexTypedRequestSchema,
   omit: ReadonlySet<string>,
   types: Readonly<Record<string, TFlexTypedRequestSchema>>,
   seen: Set<string>,
-): boolean => {
-  if (isRecord(schema.properties) && Object.keys(schema.properties).some((key) => omit.has(key))) return true;
+  found = new Set<string>(),
+): Set<string> => {
+  if (isRecord(schema.properties)) {
+    for (const key of Object.keys(schema.properties)) if (omit.has(key)) found.add(key);
+  }
   const target = referencedType(schema);
   if (target !== undefined) {
-    if (seen.has(target) || types[target] === undefined) return false;
+    if (seen.has(target) || types[target] === undefined) return found;
     seen.add(target);
-    return holdsOmitted(types[target], omit, types, seen);
+    return omittedIn(types[target], omit, types, seen, found);
   }
-  return (['allOf', 'anyOf', 'oneOf'] as const).some((key) => Array.isArray(schema[key])
-    && (schema[key] as unknown[]).some((member) => isRecord(member) && holdsOmitted(member, omit, types, seen)));
+  for (const key of ['allOf', 'anyOf', 'oneOf'] as const) {
+    const members = schema[key];
+    if (!Array.isArray(members)) continue;
+    for (const member of members) if (isRecord(member)) omittedIn(member, omit, types, seen, found);
+  }
+  return found;
 };
 
 /** Whether a call may leave out every parameter: its schema requires none. */
@@ -169,7 +176,8 @@ export async function describeTypedRequests(options: IFlexTypedRequestSurfaceOpt
     let path = base;
     for (let suffix = 2; paths.has(path); suffix++) path = `${base}_${suffix}`;
     paths.add(path);
-    const inputSchema = withoutOmitted(withDefinitionRefs(contract.request) as TFlexTypedRequestSchema, omitted, schemas);
+    const requestSchema = withDefinitionRefs(contract.request) as TFlexTypedRequestSchema;
+    const inputSchema = withoutOmitted(requestSchema, omitted, schemas);
     const docLines = [
       ...(declared.documentation ? [declared.documentation] : []),
       ...(declared.request.documentation ? [`@param params ${declared.request.documentation}`] : []),
@@ -183,6 +191,7 @@ export async function describeTypedRequests(options: IFlexTypedRequestSurfaceOpt
       summary: summaryOf(declared.documentation, contract.method),
       ...(declared.documentation ? { description: declared.documentation } : {}),
       ...(contract.deprecated ? { deprecated: true } : {}),
+      omitted: [...omittedIn(requestSchema, omitted, schemas, new Set())].sort(),
       inputSchema,
       outputSchema: withDefinitionRefs(contract.response) as TFlexTypedRequestSchema,
       declaration: `${docLines.length ? docBlock(docLines) : ''}function ${functionName}(params${optional}: ${declared.request.type}): Promise<${declared.response.type}>;`,

package/ts_typedrequest/interfaces.ts

@@ -42,6 +42,11 @@ export interface IFlexTypedRequestMethod {
   description?: string;
   /** Set by a `@deprecated` tag on the contract. */
   deprecated?: boolean;
+  /**
+   * The properties of the surface's `omit` this method's request has, itself or through the types
+   * it refers to: the ones the binding fills for its calls. Empty where it has none.
+   */
+  omitted: string[];
   /** The request's schema, without the omitted properties. */
   inputSchema: TFlexTypedRequestSchema;
   /** The response's schema. */
@@ -96,7 +101,9 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
   router: IFlexTypedRequestRouter;
   /**
    * The request properties the surface leaves out, from the run: `{ identity }` of the user the
-   * session acts for. They are merged over the model's parameters.
+   * session acts for. A call takes from it the properties its method's request has
+   * (`IFlexTypedRequestMethod.omitted`) and nothing else; a method whose request has none is called
+   * without asking.
    */
   request?(
     method: IFlexTypedRequestMethod,
@@ -116,6 +123,19 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
    * `IFlexCatalogMethod.readOnly`. Default: none.
    */
   readOnly?(method: IFlexTypedRequestMethod): boolean;
+  /**
+   * The request a call routes for the model's validated parameters, such as the parameters with the
+   * short names the model was shown for records turned back into their IDs. Default: the
+   * parameters. It runs when the call runs, after `onCall` decided it where the method has one:
+   * `onCall` and a proposal see the model's parameters. The omitted properties are dropped from what
+   * it returns, as from the model's, and only `request` fills them. A throw refuses the call with
+   * its error, and so does a result that is no object.
+   */
+  params?(
+    method: IFlexTypedRequestMethod,
+    params: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
   /**
    * What the model sees of a method's answered response, such as the response without a
    * credential's secret. Default: the response. A refusal does not reach it, and the method's

package/ts_typedrequest/readme.md

@@ -29,19 +29,21 @@ const catalog = catalogFromTypedRequests<IAppScope>(surface, {
 - Each typed method becomes a method of the path `<area>.<method>`; the area is the base name of the file that declares the contract (`vouchers` for `requests/vouchers.ts`, the folder's name for an `index.ts`), or what `area` returns. A name that is no identifier is mapped as `FlexToolCatalog.identifierOf()` maps it (`export` becomes `export_`).
 - Its declaration is the contract as written: `function getVoucher(params: { voucherId: string }): Promise<{ voucher: IVoucher }>;` after the contract's JSDoc with its tags, the request property's JSDoc as `@param params`, the response property's as `@returns`. `params` is optional where the request requires nothing.
 - Its `inputSchema` and `outputSchema` are the request's and response's JSON Schema; `execute` validates every call against the request's.
-- `omit` names request properties the binding fills from the run, such as the caller's identity or a CSRF token: they leave every request's schema and declaration, so the model can neither see nor send them.
+- `omit` names request properties the binding fills from the run, such as the caller's identity or a CSRF token: they leave every request's schema and declaration, so the model can neither see nor send them. Each method lists in `omitted` those its request has, itself or through the types it refers to; a public method's list may be empty.
 - The named types the requests and responses reach become the catalog's types, each with its JSON Schema, its declaration from the sources, or both: a generic is declared once (`IPage<T>`) and its instances have schemas (`IPage_IVoucher`). A method's result types are declared only as deep as `toolCatalog.outputTypeDepth` asks, as for any declaration.
 
 The surface is plain JSON, so a build step can write it next to the server and the server read it at startup without TypeScript or `@api.global/typedopenapi`. A 330-method API is described in about 8 seconds.
 
 `catalogFromTypedRequests(surface, options)` returns an `IFlexToolCatalog`:
 
-- `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters and what `request` returns for the omitted properties, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
+- `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
+- `request` fills the omitted properties. A call takes from what it returns only the omitted properties its method's request has, so one answer serves every method (`{ identity, csrfToken }`), and a method whose request has none is routed without asking it. A value the model passes for any omitted property never reaches the router.
 - A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
 - `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
 - `readOnly` marks the methods that only read. A marked method is declared `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may start while the model still streams, and a turn answers identical ones once; every other method's calls, gated by `onCall` or not, run in the order the model made them. Mark nothing that asks for permission.
+- `params` makes the request a call routes of the model's validated parameters, such as the parameters with the short names the model was shown for records turned back into their IDs; by default the parameters themselves. It runs when the call runs, after `onCall` decided it where the method has one, so `onCall` and a proposal see the model's parameters. The omitted properties are dropped from what it returns as from the model's, and only `request` fills them. A throw refuses the call with its error, and so does a result that is no object.
 - `response` decides what the model sees of an answered response, such as the response without a credential's secret; by default the response itself. A refusal does not reach it, and the method's declaration still shows the contract's response.
-- A surface that omits properties needs `request`; an alias for a method the surface lacks is refused.
+- A surface that omits properties needs `request`; an alias for a method the surface lacks is refused, and so is a surface whose methods have no `omitted` list, as one described by an earlier version: describe it again.
 
 ## Issue Reporting and Security