carrick 0.3.107 → 0.3.109

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

@@ -86,6 +86,12 @@ export declare class TypeInferrer {
      */
     private readonly readNodes;
     private readonly unwidenedBudgetMs;
+    /**
+     * The files a request has named to this inferrer, as the requests named
+     * them (carrick#1985). It lives as long as the project does, so the first
+     * request of a file is the first of the process, not of a batch.
+     */
+    private readonly filesAsked;
     constructor(options: TypeInferrerOptions);
     /**
      * What the structural printer needs to tell the user's own declarations from
@@ -193,6 +199,61 @@ export declare class TypeInferrer {
      */
     private resolveParamTarget;
     private inferResponseBody;
+    /**
+     * The handler a module exports on `line`: a function that opens on exactly
+     * that line, exported at the top of its module, where no call on the line
+     * registers a route (carrick#807).
+     *
+     * That is the anchor of a route its module's place in the project states:
+     * the row's line is the handler's own export, and the module's exports are
+     * how the framework finds it. Each condition keeps another kind of row out:
+     *
+     *  - the line has to be the function's first, with no tolerance. A model
+     *    row that names no site of its own can sit on any line of a handler,
+     *    and the nearest function to such a line is whatever is declared
+     *    beside it;
+     *  - a method of a class is a controller's handler, whose rows are
+     *    anchored on what a model located before the method's own return;
+     *  - a line that registers a route has a registration to read.
+     */
+    private handlerDeclaredAtLine;
+    /**
+     * `handlerDeclaredAtLine` without its registration test, for a caller that
+     * has already looked for a registration on the line.
+     */
+    private exportedFunctionOpeningOn;
+    /**
+     * The response of a handler the request's line declares, for a request
+     * that also located an expression inside it (carrick#807).
+     *
+     * The handler's own return is read first, exactly as a `function_return`
+     * request at the line reads it, and that reading stands: a body it
+     * recovered, and a decision it made not to publish one. The located
+     * expression is consulted in one case only. Where the handler returns a
+     * call nothing resolves (its library is not installed), the return walk
+     * reads no argument the source does not annotate, because it cannot tell a
+     * response sender from a query. A located payload that is an ARGUMENT of
+     * such a returned call says which it is, so the same walk runs again with
+     * that callee taken as a sender: every success body the handler returns
+     * through it, error branches dropped as before. The located expression's
+     * own type is never what is published here.
+     *
+     * Returns `undefined` when the located expression is something the return
+     * walk never looked at, so it is left to the readings below:
+     *  - the handler returns nothing (`void`): it sends through a parameter;
+     *  - the handler returns transport the walk read no body out of, and the
+     *    located expression is not part of what it returns. A body built before
+     *    the response is returned (`const res = send(body); ...; return res`)
+     *    is one. Named on a send that states an error or redirect status, it is
+     *    no success body and the row abstains.
+     */
+    private responseOfDeclaredHandler;
+    /**
+     * The call inside one of `returned` that the located expression is, or is
+     * an argument of: the send a located payload was handed to. `undefined`
+     * when the located expression is not part of what the handler returns.
+     */
+    private returnedSendHolding;
     /**
      * True when a located call's own result is the route's payload, so the
      * transitional drill into its first argument must not run (carrick#1732).
@@ -297,6 +358,14 @@ export declare class TypeInferrer {
      * else, and is not reported.
      */
     private statedBodyAtRead;
+    /**
+     * The type node `statedBodyAtRead` reads, for a caller that wants the
+     * annotation itself: a consumer's response read reports its root, and a
+     * handler's request read prints it (carrick#807). One reading of "stated at
+     * the read" for both, so the two cannot disagree about which annotation
+     * belongs to a read.
+     */
+    private typeNodeStatedAtRead;
     /**
      * A stated type with `any` or `unknown` written anywhere in it (`unknown`,
      * `Record<string, unknown>`, `{ items: any[] }`) leaves a position open: it
@@ -892,9 +961,22 @@ export declare class TypeInferrer {
      *
      * Under `statedOnly` the annotation is the ONLY thing that counts, so an
      * unresolvable callee's arguments never become a contract by accident.
+     *
+     * `asSent` judges the object in the form it is sent in, which is what an
+     * ARGUMENT handed to a sender is asked; see `typeIsObjectShaped`.
      */
     private nodeCarriesPayloadContract;
-    /** Object, array-of-object, or a union/intersection containing one. */
+    /**
+     * Object, array-of-object, or a union/intersection containing one.
+     *
+     * With `asSent` the object is judged in the form it is SENT in
+     * (carrick#1163): a value that declares `toJSON()` travels as what that
+     * returns. A `URL` or a `Date` is therefore the string it serialises to,
+     * the bare primitive this rule already refuses, and `redirect(new URL(path,
+     * base))` hands over a location exactly as `redirect("/next")` does
+     * (carrick#807). A value whose JSON form is itself an object is a body like
+     * any other.
+     */
     private typeIsObjectShaped;
     /**
      * The `satisfies X` / `as X` / `<X>` annotation node on an expression, when
@@ -1104,6 +1186,17 @@ export declare class TypeInferrer {
      * keep both segments.
      */
     private declaringPackageOf;
+    /**
+     * The declaration a symbol is attributed to (carrick#2031). One declaration
+     * is itself. Where several files merge one symbol (a global interface the
+     * compiler's library declares and a typings package augments), their order
+     * is the order the checker merged them in, and on TypeScript 6 that changes
+     * once the program is rebuilt, so the first one is not an answer. The
+     * compiler's default library wins where it declares the symbol; otherwise,
+     * and among the library's own files, the declaring file whose path sorts
+     * first, then the earliest declaration in it.
+     */
+    private attributedDeclaration;
     /**
      * The awaited return type of the member invoked on the receiver. Reported as
      * a fact next to the receiver; a caller that classified on it alone would be
@@ -1275,6 +1368,46 @@ export declare class TypeInferrer {
      * Returns null (not a spurious type) for a genuinely payload-less handler.
      */
     private inferRequestReadFromHandler;
+    /**
+     * The call in a handler that reads the request's body off the platform
+     * request the handler was handed, or `undefined` (carrick#807).
+     *
+     * Read by shape, with no method name consulted:
+     *
+     *  - a call that takes nothing, on a member of a value whose type is request
+     *    machinery (`typeIsFrameworkMachinery`: declared by the platform or an
+     *    installed library, and carrying its body readers);
+     *  - that value is rooted at one of the handler's OWN parameters, named or
+     *    destructured. A response read off an outbound call inside the handler
+     *    (`(await upstream.json()) as Rate`) has the same shape one variable
+     *    away, and is the opposite side of a different exchange;
+     *  - and the call's result, awaited, is `any` or `unknown`: the platform's
+     *    untyped parse. A read that states its own type (`formData()`, a typed
+     *    `json<T>()`) is not this shape and is left to the readers that
+     *    already handle it.
+     *
+     * The first such call in source order: a body is read once.
+     */
+    private platformBodyReadIn;
+    /**
+     * The request contract the source states AT a body read, or null when it
+     * states none there (carrick#807).
+     *
+     * Three statements count, each of them on the read itself:
+     *
+     *  - 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.
+     *
+     * The first two are `typeNodeStatedAtRead`, the reading a consumer's
+     * response read already gets. An annotation further out is not one of them:
+     * `const saved: Saved = await save(await request.json())` types what `save`
+     * returned, and reading it as the body would publish the wrong side of the
+     * handler. Nor is a placeholder (`as unknown`, `Record<string, unknown>`).
+     */
+    private requestStatedAtBodyRead;
     /**
      * Resolve a type-annotation/type-argument node to fully-structural text,
      * dropping any `Promise<…>` wrapper (`c.req.json<T>()` returns `Promise<T>`,
@@ -1418,8 +1551,31 @@ export declare class TypeInferrer {
      * request type resolves `body` to `unknown`/`any`, which the useless-type
      * guard rejects. So a handler that declares nothing yields null and the next
      * anchor runs.
+     *
+     * The member has to be one the route's own annotation can have filled
+     * (carrick#807). The platform `Request` declares `body` too, as the byte
+     * stream every request carries, and so does each library type that extends
+     * it. That is concrete, so it passed the useless-type guard and a handler
+     * taking the platform request published a stream as its request contract,
+     * ahead of the body read inside it. A `body` a library declares with one
+     * fixed type says nothing about this route and is skipped.
      */
     private requestBodyFromHandlerParams;
+    /**
+     * True when a member is declared by a library, or by the platform, with a
+     * type that names none of its declaring type's parameters: the same type on
+     * every value, whichever route the value belongs to.
+     *
+     * `body: ReqBody` on a request type generic in its body is a slot, and the
+     * handler's annotation fills it. `readonly body: ReadableStream<Uint8Array>
+     * | null` on the platform request is not. A member the repo declares itself
+     * is never fixed in this sense: writing `body: NewWidget` on the handler's
+     * own request type is the annotation, and one declaration of the repo's
+     * among several (an intersection with the platform type) decides it. A
+     * declaration that states no type at all is left to the guards that read
+     * the type.
+     */
+    private memberIsFixedByItsLibrary;
     /**
      * Anchor (b2): the contract declared by a VALIDATOR MIDDLEWARE on the
      * registration (carrick#964).