Libraries v5.0.0
    Preparing search index...

    Class PolymorphicQueryBuilder<S, B, P, Connected>

    Immutable polymorphic read graph. Branches are combined in one PostgreSQL statement; rowSchema is a real discriminated union and variantRowSchemas supplies object schemas for separately configured mappers. Framework does not choose application DTO mappings.

    Type Parameters

    Hierarchy

    Index
    "[PARAMETER_READER]": PolymorphicParameterReader

    Type-only fluent return constructor.

    "[PARAMETER_STATE]": P

    Type-only ordered argument contract.

    "[READ_QUERY]": true

    Nominal identity for typed child-query customizers.

    Runtime union matching decoded results, including selected variant bodies.

    variantRowSchemas: Readonly<B>

    Stable object schemas keyed by discriminator, suitable for mapper.configure().

    • get returnsEntityRows(): boolean

      True when all branches retain complete entity rows.

      Returns boolean

    • Internal

      Shared parameter plan across union branches and included relations.

      Returns CompiledReader

    • Parameters

      • predicate: ReadPredicate

      Returns this

    • Configure a captured union SELECT and declare its complete raw output shape.

      Type Parameters

      Parameters

      • configure: (query: QueryBuilder) => QueryBuilder<any, any> | undefined
      • options: QueryOutput<O>

      Returns OpaqueQuery<O>

    • Internal

      Compile one UNION ALL statement; JSON preserves distinct branch shapes.

      Parameters

      • Optionalcorrelate: ReadCorrelation
      • Optionalmode: typeof COMPILE_PARAMETERS

      Returns QueryBuilder

    • Count matching rows across variants, excluding global pagination and ordering.

      Returns Promise<number>

    • Internal

      Decode using exactly the selected branch's schema and codecs.

      Parameters

      • row: any
      • Optionalpath: string

      Returns InferType<B[keyof B]> extends undefined ? never : InferType<B[keyof B]>

    • Execute and decode one statement containing every requested branch.

      Returns Promise<
          (
              InferType<B[keyof B]> extends undefined ? never : InferType<B[keyof B]>
          )[],
      >

    • Return the first globally ordered row, or undefined.

      Returns Promise<
          | (
              InferType<B[keyof B]> extends undefined ? never : InferType<B[keyof B]>
          )
          | undefined,
      >

    • Load a common relation on every branch, configuring the child exactly once.

      Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              {
                  [P in string
                  | number
                  | symbol]: ObjectSchemaBuilder<
                      SchemaProps<B[P]> & {
                          -readonly [R in string]-?: RelationField<
                              ReadRelations<S>[K],
                              Child["rowSchema"],
                          >
                      },
                      true,
                      false,
                      undefined,
                      false,
                      {},
                      [],
                  >
              },
              AttachParameters<P, ParametersOf<Child>, `relation:${K}`>,
              Connected,
          >,
          Connected,
      >

    • Customize a relation on one discriminator branch.

      Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              R extends keyof ReadRelations<S>
              | keyof ReadRelations<VariantBody<S, K>>
                  ? Omit<B, K> & Record<
                      K,
                      ObjectSchemaBuilder<
                          SchemaProps<B[K]> & {
                              -readonly [F in string]-?: RelationField<
                                  ((...) & (...))[F],
                                  Child["rowSchema"],
                              >
                          },
                          true,
                          false,
                          undefined,
                          false,
                          {},
                          [],
                      >,
                  >
                  : B,
              AttachParameters<
                  P,
                  MergeParameters<ScopedParameters<P, `variant:${K}`>, ParametersOf<Child>>,
                  `variant:${K}`,
              >,
              Connected,
          >,
          Connected,
      >

    • Internal

      Capture native primary keys for a single writable ORM variant.

      Parameters

      • variantKey: string

      Returns QueryBuilder

    • Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Type Parameters

      • const A extends readonly RawBinding[]

      Parameters

      • sql: string
      • bindings: A & WithoutParameters<NoInfer<A>>

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              P extends ParameterState ? P : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Parameters

      • sql: string

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              P extends ParameterState ? P : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Globally paginate the discriminated union, leaving the source and its metadata unchanged.

      Parameters

      • __namedParameters: { page: number; pageSize: number }

      Returns Promise<
          PaginationResult<
              InferType<B[keyof B]> extends undefined ? never : InferType<B[keyof B]>,
          >,
      >

    • Read a property common to the selected variants; returned scalar values are detached.

      Type Parameters

      • K extends string | number | symbol

      Parameters

      • key: K

      Returns Promise<
          (
              InferType<B[keyof B]> extends undefined ? never : InferType<B[keyof B]>
          )[K][],
      >

    • Returns ReadPredicateContext<ReadColumns<S, keyof ReadRelations<S>>>

    • Internal

      Check the identity of the original read source, retained by clones.

      Parameters

      • other: unknown

      Returns boolean

    • Select trusted SQL from the union envelope with an explicit output contract.

      Type Parameters

      Parameters

      • sql: string
      • bindings: readonly RawBinding[]
      • options: QueryOutput<O>

      Returns OpaqueQuery<O>

    • Restrict returned discriminator branches and narrow both runtime and inferred schemas.

      Type Parameters

      • const K extends readonly (keyof B & string)[]

      Parameters

      • keys: K

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              Pick<B, K[number]>,
              SelectParameterVariants<P, K[number]>,
              Connected,
          >,
          Connected,
      >

    • Awaiting deliberately executes the query each time.

      Type Parameters

      • T = (InferType<B[keyof B]> extends undefined ? never : InferType<B[keyof B]>)[]
      • E = never

      Parameters

      • Optionalresolve:
            | (
                (
                    rows: (
                        InferType<B[keyof B]> extends undefined
                            ? never
                            : InferType<B[keyof B]>
                    )[],
                ) => T | PromiseLike<T>
            )
            | null
      • Optionalreject: ((error: any) => E | PromiseLike<E>) | null

      Returns Promise<T | E>

    • Return a separately mutable Knex snapshot of the union statement.

      Returns QueryBuilder

    • Render debugging SQL without performing any database calls.

      Returns string

    • Type Parameters

      • S extends string | ((columns: C) => AliasedColumn<any>)
      • const A extends readonly [unknown, unknown]

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Type Parameters

      Parameters

      • column: S
      • value: A & (
            A extends QueryParameter<string>
                ? CheckParameterValue<
                    P,
                    NoInfer<A>,
                    PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                >
                : string
        )

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Match a fixed value tuple or captured SELECT subquery.

      Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Type Parameters

      Parameters

      • column: S
      • value: A & (
            A extends QueryParameter<string>
                ? CheckParameterValue<
                    P,
                    NoInfer<A>,
                    PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                >
                : string
        )

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Negate equality while preserving ordinary SQL null semantics.

      Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Type Parameters

      • S extends string | ((columns: C) => AliasedColumn<any>)
      • const A extends readonly [unknown, unknown]

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Type Parameters

      Parameters

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              ValueParameters<
                  P,
                  A,
                  PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
              > extends ParameterState
                  ? ParameterState & ValueParameters<
                      P,
                      A,
                      PredicateValue<ReadColumns<S, keyof ReadRelations<S>>, S>,
                  >
                  : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Trusted SQL with concrete bindings; use a typed predicate for placeholders.

      Type Parameters

      • const A extends readonly RawBinding[]

      Parameters

      • sql: string
      • bindings: A & WithoutParameters<NoInfer<A>>

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              P extends ParameterState ? P : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Trusted SQL with concrete bindings; use a typed predicate for placeholders.

      Parameters

      • sql: string

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              P extends ParameterState ? P : never,
              Connected extends true ? true : false,
          >,
          Connected extends true ? true : false,
      >

    • Filter one branch using schema property names; other variants remain unaffected.

      Type Parameters

      • K extends string
      • Sel extends string | ((columns: C) => AliasedColumn<any>)
      • const A

      Parameters

      • key: K
      • selector: Sel
      • operator: string
      • value: A & CheckParameterValue<
            P,
            NoInfer<A>,
            PredicateValue<ReadColumns<BranchSource<S, K>>, Sel>,
        >

      Returns QueryView<
          PolymorphicQueryBuilder<
              S,
              B,
              AttachParameters<
                  P,
                  ValueParameters<
                      ScopedParameters<P, `variant:${K}`>,
                      A,
                      PredicateValue<ReadColumns<BranchSource<S, K>>, Sel>,
                  >,
                  `variant:${K}`,
              >,
              Connected,
          >,
          Connected,
      >