@code0-tech/triangulum 0.37.2 → 0.38.0

package/dist/util/subflows.util.d.ts

@@ -1,5 +1,6 @@
 import { default as ts } from 'typescript';
-import { FunctionDefinition, SubFlowValue } from '@code0-tech/sagittarius-graphql-types';
+import { FunctionDefinition } from '@code0-tech/sagittarius-graphql-types';
+import { SuggestionCandidate } from './suggestion.util';
 /**
  * Extracts and creates a list of SubFlowValue objects from function declarations
  * that are compatible with the given parameter type.
@@ -13,7 +14,8 @@ import { FunctionDefinition, SubFlowValue } from '@code0-tech/sagittarius-graphq
  * @param {FunctionDefinition[]} functions - Array of function definitions for reference lookup
  * @param {ts.Type} paramType - The target parameter type that functions must be compatible with
  *
- * @returns {SubFlowValue[]} An array of SubFlowValue objects for compatible functions,
- *          or an empty array if the paramType is not a sub-flow type
+ * @returns {SuggestionCandidate[]} An array of sub-flow candidates for compatible
+ *          functions, each carrying how certainly it satisfies the slot, or an
+ *          empty array if the paramType is not a sub-flow type
  */
-export declare const getSubFlows: (checker: ts.TypeChecker, functionDeclarations: ts.FunctionDeclaration[], functions: FunctionDefinition[], paramType: ts.Type) => SubFlowValue[];
+export declare const getSubFlows: (checker: ts.TypeChecker, functionDeclarations: ts.FunctionDeclaration[], functions: FunctionDefinition[], paramType: ts.Type) => SuggestionCandidate[];

package/dist/util/suggestion.util.d.ts

@@ -0,0 +1,161 @@
+import { default as ts } from 'typescript';
+import { LiteralValue, NodeFunction, ReferenceValue, SubFlowValue } from '@code0-tech/sagittarius-graphql-types';
+/**
+ * A value a slot can be filled with: a literal option of the slot's own type, a
+ * reference to something already in scope, a function node whose result is fed
+ * into the slot, or a function bound as a sub-flow.
+ */
+export type SuggestionValue = NodeFunction | ReferenceValue | LiteralValue | SubFlowValue;
+/**
+ * How certain it is that a suggestion actually produces the slot's type.
+ *
+ * - `exact`: the candidate's own type is assignable to the slot's type. Picking
+ *   it always yields a value the slot accepts.
+ * - `possible`: the match was only reached by weakening one of the two sides —
+ *   the candidate *can* produce a fitting value, but is not guaranteed to. See
+ *   {@link SuggestionMatchReason} for what was weakened.
+ *
+ * Both kinds are offered: a `possible` candidate is frequently the one the user
+ * wants (a generic `std::object::get`, a reference into an optional field). The
+ * distinction exists so a consumer can tell "this slot has dedicated producers"
+ * from "everything happens to fit here", and because a `possible` pick is the
+ * case that may need a cast to type-check.
+ */
+export type SuggestionMatch = "exact" | "possible";
+/**
+ * Why a suggestion matched only possibly.
+ *
+ * - `unconstrained`: one of the two sides constrains nothing (`any`, `unknown`,
+ *   `{}`) — the candidate fits every slot, or the slot is fit by every candidate.
+ *   Either way the match says nothing about this pairing.
+ * - `generic`: the candidate's type is a type parameter and the match was made
+ *   against its constraint. A concrete instantiation may be narrower.
+ * - `union-member`: the candidate is a union and only some of its members fit.
+ *   Which member materializes is a runtime decision.
+ * - `nullable`: the candidate may be `null`/`undefined` where the slot is not.
+ *
+ * Listed weakest first: a candidate weakened on several axes reports the first
+ * of these that applies (see {@link weakestCertainty}).
+ */
+export type SuggestionMatchReason = "unconstrained" | "generic" | "union-member" | "nullable";
+/**
+ * The certainty of a single suggestion. `reason` is present exactly when
+ * `match` is `possible`.
+ */
+export interface SuggestionCertainty {
+    match: SuggestionMatch;
+    reason?: SuggestionMatchReason;
+}
+/**
+ * A suggestion together with its certainty — the form suggestions travel in
+ * while a schema is being built.
+ *
+ * On the finished schema the two halves are split into the index-aligned
+ * `suggestions` / `suggestionCertainty` pair (see {@link Input}) so the
+ * suggestion values stay plain GraphQL values a consumer can use as-is. Every
+ * step in between passes candidates around instead of the two arrays, so the
+ * alignment cannot drift.
+ */
+export interface SuggestionCandidate {
+    value: SuggestionValue;
+    certainty: SuggestionCertainty;
+}
+/** The certainty of a candidate that is guaranteed to fit its slot. */
+export declare const EXACT_MATCH: SuggestionCertainty;
+/** The certainty of a candidate that fits only under the given condition. */
+export declare const possibleMatch: (reason: SuggestionMatchReason) => SuggestionCertainty;
+/** Pairs each value with {@link EXACT_MATCH}, for sources that cannot be weakened. */
+export declare const exactCandidates: (values: SuggestionValue[]) => SuggestionCandidate[];
+/**
+ * Picks the stronger of two certainties for the same value — `exact` wins, and
+ * among two `possible` ones the first is kept. Used when the same suggestion is
+ * collected twice against differently scoped types (see the merge in
+ * getSignatureSchema): the slot accepts it for the better of the two reasons.
+ */
+export declare const strongerCertainty: (a: SuggestionCertainty, b: SuggestionCertainty) => SuggestionCertainty;
+/**
+ * Picks the weakest of the given certainties: a candidate weakened on more than
+ * one axis (e.g. a generic return that also turns out to be `any`) is only as
+ * strong as its weakest link. `exact` is the result only when nothing was
+ * weakened at all.
+ */
+export declare const weakestCertainty: (...certainties: SuggestionCertainty[]) => SuggestionCertainty;
+/**
+ * True for a type that constrains nothing, so an assignability test against it
+ * is vacuous: `any` and `unknown`, the empty object type — `{}`, which every
+ * non-nullish value satisfies and which is what a generic `OBJECT<T>` or an
+ * uninstantiated payload bound resolves to — and an object whose only structure
+ * is an index signature that says nothing about its values either. That last
+ * case is what an `OBJECT<T>` instantiated without an argument resolves to:
+ * `{[key: string]: any}`, a slot every object fits. A signature with a real
+ * value type (`Record<string, NUMBER>`) does constrain, and keeps its slot
+ * concrete.
+ *
+ * It matters on both sides of a match. A candidate of this type fits every slot,
+ * and a *slot* of this type is fitted by every candidate — the second case is
+ * the one that would otherwise report a hundred exact "producers" for a slot
+ * that simply accepts anything.
+ *
+ * A callable, an array and anything with properties is excluded: those
+ * constrain their values. An index signature is inspected only `depth` levels
+ * deep (one, from the outside) because an index type may refer back to its own
+ * container (`type Json = {[key: string]: Json}`).
+ */
+export declare const isUnconstrainedType: (type: ts.Type | undefined, depth?: number) => boolean;
+/**
+ * Decides whether a candidate type fits an expected (slot) type, and how
+ * certainly — the shared rule behind every assignability-based suggestion
+ * source.
+ *
+ * Returns `null` when the candidate does not fit at all. Otherwise the match is
+ * `exact`, or `possible` with the reason the fit is not guaranteed:
+ *
+ * - either side constrains nothing (`any`, `unknown`, `{}`) → `unconstrained`.
+ *   For the candidate that means it fits everywhere; for the slot that it is
+ *   fitted by everything. Neither tells the consumer that this candidate is a
+ *   producer *of this type*, which is the whole point of the distinction. This
+ *   only *weakens* the verdict — whether the candidate fits at all is still
+ *   decided by assignability, so an open candidate is not waved through into a
+ *   slot that would reject it;
+ * - the candidate is a union and only some members fit → `union-member`. A
+ *   union is only assignable as a whole when *every* member is, so the partial
+ *   case is exactly the one strict assignability would reject while the slot can
+ *   still be served at runtime;
+ * - the candidate may be nullish where the slot is not → `nullable`. The nullish
+ *   part is deliberately ignored for matching (a `string | null` producer is a
+ *   useful suggestion for a `string` slot), which is what makes the distinction
+ *   worth reporting.
+ *
+ * A purely nullish candidate strips down to `never`, which is assignable to
+ * anything, and is therefore rejected explicitly.
+ */
+export declare const typeMatchCertainty: (type: ts.Type, checker: ts.TypeChecker, expectedType: ts.Type) => SuggestionCertainty | null;
+/**
+ * Reads a schema's suggestions back as candidates. A schema that carries
+ * suggestions without certainties (produced before the pair existed, or hand
+ * written) is read as fully exact rather than rejected.
+ */
+export declare const suggestionCandidates: (schema: {
+    suggestions?: SuggestionValue[];
+    suggestionCertainty?: SuggestionCertainty[];
+}) => SuggestionCandidate[];
+/**
+ * Splits candidates into the schema's index-aligned pair of keys, both keys
+ * always present — the convention of a freshly collected schema, which carries
+ * the keys even when nothing matched (an empty array marks "this is an input
+ * slot and these are all its candidates", which normalizeNodeSchema then
+ * collapses). Use {@link suggestionFields} everywhere else.
+ */
+export declare const suggestionPair: (candidates: SuggestionCandidate[]) => {
+    suggestions: SuggestionValue[];
+    suggestionCertainty: SuggestionCertainty[];
+};
+/**
+ * Splits candidates back into the schema's index-aligned pair of keys. Both keys
+ * are omitted for an empty set, matching the convention that a schema without
+ * suggestions carries neither key.
+ */
+export declare const suggestionFields: (candidates: SuggestionCandidate[] | undefined) => {
+    suggestions?: SuggestionValue[];
+    suggestionCertainty?: SuggestionCertainty[];
+};