carrick 0.3.124 → 0.3.126

package/sidecar/dist/src/type-inferrer.d.ts

@@ -479,11 +479,29 @@ export declare class TypeInferrer {
      * guard, so that binding stays unread and the capture answers the row.
      */
     private destructuredValueTerminal;
+    /**
+     * Between `callExpr` and the return statement around it there is an object
+     * or array literal: the call's result is one part of a value the function
+     * builds and returns.
+     */
+    private callIsPartOfReturnedLiteral;
     /**
      * `expr` declares a name for what a call returns when it is handed a
      * tracked name whole (`const data: T = await parseJson(response, 'op')`).
      */
     private handsTrackedValueToACall;
+    /**
+     * The call whose result `expr` declares or assigns a name for, and the
+     * index of its argument that is a tracked name whole, or undefined.
+     */
+    private callTakingTrackedValue;
+    /**
+     * `expr` names the result of a call that states the tracked value it takes
+     * (`callStatesItsArgument`): a schema validates it, or the callee returns it
+     * unchanged. A converter's result describes what it built from the value,
+     * not the value (carrick#2595).
+     */
+    private statesTrackedValue;
     /** `expr` holds a binary whole-body read taken on a tracked name. */
     private holdsBinaryBodyRead;
     /**
@@ -696,7 +714,10 @@ export declare class TypeInferrer {
      *    serialiser answering `string` describes what the caller did with the
      *    body, not what the body is, and publishing it would be a
      *    concrete-but-wrong contract where the honest `any` of the read is
-     *    merely unresolved.
+     *    merely unresolved;
+     *  - the call states its argument (`callStatesItsArgument`): a schema
+     *    validates it, or the callee returns it unchanged. A converter's
+     *    object result describes what it built, not the body (carrick#2595).
      */
     private statedPayloadAroundBodyRead;
     /**
@@ -1800,8 +1821,10 @@ export declare class TypeInferrer {
      *  - a cast on it: `(await request.json()) as NewWidget`;
      *  - the annotation of the binding it initialises:
      *    `const input: NewWidget = await request.json()`;
-     *  - a schema the read, or the binding that holds it, is handed to
-     *    (`schemaConsumingRead`): the schema's input is what a caller may send.
+     *  - a type the handler states for the read further on
+     *    (`statedInFunction`): a schema it is handed to, the annotation of a
+     *    name it is assigned to, a pass-through function, a cast of the whole
+     *    value.
      *
      * The first two are `typeNodeStatedAtRead`, the reading a consumer's
      * response read already gets. An annotation further out is not one of them:
@@ -1904,6 +1927,62 @@ export declare class TypeInferrer {
      * whose type does not resolve the member, or an opaque config, abstains.
      */
     private requestBodyInCall;
+    /**
+     * carrick#2628: the located node is an argument of a call into a function
+     * whose body the program holds (an in-repo client method,
+     * `client.addTags(project, unique(tags))`), at a parameter that is not a
+     * body slot. What the call sends is decided inside that function, so the
+     * argument is the body only when the function sends it unchanged. One
+     * level, read off each use of the parameter in the function's body:
+     *
+     *  - the use IS the value of a body-named member (`body: tags`,
+     *    `body: JSON.stringify(tags)`) or of a body slot of a call: the
+     *    argument is the body, and its own type stands (`none`);
+     *  - the use sits inside such a value (`body: { tags }`,
+     *    `body: (event ?? {}) as never`): the body is that value, read at the
+     *    function without the casts around it;
+     *  - the use sits inside an object or array literal that is no body value
+     *    (`send(project, [labels])`): the body cannot be told, abstain.
+     *
+     * Uses that disagree abstain. A generic function's body may be typed by
+     * its type parameters, so it abstains too. A library's declaration
+     * (`fetch`, an installed client) has no body to read and is left alone,
+     * and so is an untyped argument (a handler's `request.body` handed to a
+     * helper): it states no contract to mistake, and the untyped-read path
+     * below reads it.
+     */
+    private bodyBuiltByCallee;
+    /**
+     * The request body value `use` is part of, inside `scope`: the value of a
+     * body-named object member, or the argument at a body slot of a call,
+     * looking through parentheses, casts, `await` and a `JSON.stringify`
+     * around it. `use` itself when it is that value whole.
+     */
+    private bodyValueAround;
+    /** `value` is `use` behind what `sentValue` sees through. */
+    private isSameValue;
+    /**
+     * The value a body slot sends when it sends anything, behind parentheses,
+     * casts, `await`, a `JSON.stringify`, and (carrick#2668) a choice whose
+     * other side sends nothing: `x ? JSON.stringify(x) : undefined`,
+     * `x || null`, `x ?? undefined`. A `?? {}` sends `{}`, so it is a body the
+     * function builds and is not seen through.
+     */
+    private sentValue;
+    /**
+     * The branch of `choice` that sends something, when its other branch sends
+     * nothing (`undefined`, `null`, `void 0`, or `{}` spread into a request).
+     */
+    private sendingBranch;
+    /** `undefined`, `null`, `void 0`, or (where `emptyObject`) `{}`. */
+    private sendsNothing;
+    /**
+     * carrick#2668, #2664: `use` sits in the test of a choice whose other side
+     * sends nothing (`body ? JSON.stringify(body) : null`,
+     * `...(body === undefined ? {} : { body: JSON.stringify(body) })`). The
+     * test only decides whether the argument is sent.
+     */
+    private inSendNothingTest;
     /** A string, a string literal, a template literal, or a union of strings. */
     private isStringLikeType;
     /**
@@ -2030,19 +2109,74 @@ export declare class TypeInferrer {
      */
     private middlewareBodySchemaValues;
     /**
-     * The contract of the schema a handler validates an untyped body read with
-     * (carrick#1166), or null.
-     *
-     * `read` is the located expression: the read call, or the binding that holds
-     * it. Every call in the enclosing function that takes that value as an
-     * argument is a candidate, and the schema is the call's receiver
-     * (`Schema.safeParse(body)`) or one of its other arguments
-     * (`parse(Schema, body)`). A candidate counts only when it declares schema
-     * types (`schemaOutputType` / `schemaInputType`), so a logger or a service
-     * call the body is also handed to is never read as a contract. No method or
-     * library name is matched.
-     */
-    private schemaConsumingRead;
+     * The type the function a value is made in states for it, where the
+     * compiler types the value itself `any` or `unknown` (carrick#2594), or
+     * null.
+     *
+     * `value` is the located expression: a body read, or a call whose result is
+     * untyped. The value is followed through the names that hold it: a
+     * declaration it initialises, and a name it is assigned to later
+     * (`let body: unknown; body = await read()`). At each place the value or
+     * one of those names is used whole, the source can state a type:
+     *
+     *  0. the annotation of the name that holds it (`let body: Upload`), or the
+     *     declared return type of the function that returns it unchanged (only
+     *     with `reads.returned`);
+     *  1. a schema it is handed to (`Schema.safeParse(body ?? {})`,
+     *     `parse(Schema, body)`): the schema's input is what a sender may send
+     *     (carrick#1166). A candidate counts only when it declares schema types,
+     *     so no method or library name is matched;
+     *  2. a function of the project it is handed to that returns that argument
+     *     unchanged (through casts) or an empty default: its declared return
+     *     type. A function that builds a new value from its argument is a
+     *     converter, and its return type describes what it built, never the
+     *     value it was handed, so it states nothing here;
+     *  3. a cast of the whole value (`(body as { phone: string }).phone`);
+     *  4. the parameter of a call it is handed to (only with
+     *     `reads.parameters`), where that parameter's type is a body shape once
+     *     any callable member is dropped (a function never crosses the wire).
+     *
+     * The first rank with an answer decides. A placeholder (`unknown`,
+     * `Record<string, unknown>`, any type node with `any` or `unknown` written
+     * in it) states nothing, and two different statements in one rank decide
+     * nothing: the answer is null.
+     */
+    private statedInFunction;
+    /**
+     * What a call that takes the value at argument `index` states for it:
+     * a schema among its receiver and other arguments (rank 1), a callee of the
+     * project that returns that argument unchanged (rank 2), or, with
+     * `reads.parameters`, the parameter's own type (rank 4).
+     */
+    private stateAtReceivingCall;
+    /**
+     * The input contract of a schema `call` validates its argument at `index`
+     * with: its receiver (`Schema.safeParse(body)`) or one of its other
+     * arguments (`parse(Schema, body)`), or null. A candidate counts only when
+     * it declares schema types, so no method or library name is matched
+     * (carrick#1166).
+     */
+    private schemaHandedArgument;
+    /**
+     * `call`'s result describes the value it takes at argument `index`: it
+     * validates it with a schema, or its callee returns it unchanged
+     * (`passThroughFunction`). Any other call builds something new from the
+     * value, and its result describes what it built, never the value it was
+     * handed (carrick#2595).
+     */
+    private callStatesItsArgument;
+    /**
+     * The project function `call` invokes, when every value it returns is its
+     * argument at `index` as it was handed in (through parentheses, casts,
+     * `satisfies` and `!`) or an empty default (`{}`, `[]`, `null`,
+     * `undefined`), and at least one return is that argument. Such a function
+     * narrows its argument, so its declared return type describes the value it
+     * was handed. Any other function builds something new from it, and is not
+     * this.
+     */
+    private passThroughFunction;
+    /** `{}`, `[]`, `null` or `undefined`: a default that states no member. */
+    private isEmptyDefault;
     /**
      * The part a validated read names when that part is not a body, or
      * `undefined` (carrick#1166).