kern-orm 0.0.0-stage → 0.1.0

package/dist/index-Chr-UK_t.d.mts

@@ -0,0 +1,134 @@
+import { Cn as Operand, Dn as AnyTable, K as SchemaContext, L as NoRelations, Sn as ComparisonSignature, St as FilteredStateRows, Tt as TableOrQuery, Wn as ResultRows, X as UsableRelation, Z as UsedRelation, a as UntypedExpression, er as Type, gn as EqualityOperator, gr as GenericOperator, hn as SelectQueryState, hr as OperatorDefinitions, mn as QueryStateOf, mt as MergeSelection, on as OneRow, pt as HelperFields, r as Expression, t as AnyExpression, vr as OperatorSignature, w as SelectQueryKind, wn as OperandValue, wt as SelectQuery, xn as BooleanResult, xt as ChangeState, yn as InSignature } from "./expression-Bc-s_0qJ.mjs";
+/** Operators of ordered types: those of `equalityOperators`, and `lt`, `lte`, `gt`, and `gte` comparing with operands of the expression type. */
+declare const orderingOperators: {
+  eq: EqualityOperator<ComparisonSignature>;
+  ne: EqualityOperator<ComparisonSignature>;
+  in: EqualityOperator<InSignature>;
+  lt: GenericOperator<ComparisonSignature, AnyExpression<unknown, unknown>>;
+  lte: GenericOperator<ComparisonSignature, AnyExpression<unknown, unknown>>;
+  gt: GenericOperator<ComparisonSignature, AnyExpression<unknown, unknown>>;
+  gte: GenericOperator<ComparisonSignature, AnyExpression<unknown, unknown>>;
+};
+/** Signature of pattern matching: patterns stay strings even when the text values are transformed. */
+interface PatternSignature extends OperatorSignature {
+  readonly method: <V extends Operand<string>>(pattern: V) => Expression<BooleanResult<this["T"] | OperandValue<V>>>;
+}
+/**
+ * Operators of text types: pattern matching with `LIKE` and `ILIKE`.
+ *
+ * A string pattern is sent as it is; `param(type, pattern)` encodes it with a type.
+ */
+declare const textOperators: {
+  like: GenericOperator<PatternSignature, AnyExpression<string | null, unknown>>;
+  ilike: GenericOperator<PatternSignature, AnyExpression<string | null, unknown>>;
+};
+/**
+ * State of the query that the callback of a helper of table `T` with schema context `C` receives: the fields of the query the helper is applied to, and all its rows.
+ *
+ * It is guaranteed, so that the state that the callback returns tells whether the callback ends the guarantee of the query the helper is applied to.
+ */
+interface HelperState<T extends AnyTable, C extends SchemaContext> extends QueryStateOf<T, C> {
+  readonly result: HelperFields<never>;
+  readonly input: never;
+  readonly rows: "many";
+  readonly value: false;
+  readonly uses: never;
+  readonly guaranteed: true;
+  readonly aggregate: false;
+}
+/**
+ * Effect of a helper: the fields it selects, its rows mode on a query of many rows, `one` after `take` or `required` and `nullable` or `optional` after the method of the same name, the relations it selects records of, and whether it keeps the guarantee of the row of a query of a required relation.
+ *
+ * `reads` are the relations of the schema of the helper among them, which its callback may read from the references of the query it is applied to, and `key` is the key of its table there.
+ */
+interface HelperEffect {
+  readonly fields: object;
+  readonly rows: ResultRows;
+  readonly uses: UsedRelation;
+  readonly reads: UsedRelation;
+  readonly key: string;
+  readonly guaranteed: boolean;
+}
+/** Effect of a helper whose callback returns a query of state `S`, for each state of a union. */
+type ReadEffect<S extends SelectQueryState> = S extends SelectQueryState ? {
+  readonly fields: { [K in keyof S["result"] as K extends keyof HelperFields ? never : K]: S["result"][K]; };
+  readonly rows: S["rows"];
+  readonly uses: S["uses"];
+  readonly reads: Extract<UsableRelation<S["schema"]["relations"]>, S["uses"]>;
+  readonly key: S["schema"]["key"];
+  readonly guaranteed: S["guaranteed"];
+} : never;
+/** Error of a helper that a query does not accept, or whose callback returns a query it does not accept. */
+interface HelperError<Message extends string> {
+  readonly error: Message;
+}
+/** `unknown` when every result state retains the input marker and returns records, or the error. */
+type CheckResult<S extends SelectQueryState> = [S] extends [{
+  readonly result: HelperFields;
+  readonly value: false;
+}] ? unknown : HelperError<"A helper can filter, select fields, and take one row, but cannot clear the selection or use get, pluck, or aggregates">;
+/** State of a query over table `T` that accepts a helper of effect `E`. */
+type HelperInput<T extends AnyTable, E extends HelperEffect> = QueryStateOf<T, ReadsContext<E>> & ValueCheck<E>;
+/** Constraint of `value` of a query that accepts a helper of effect `E`. */
+type ValueCheck<E extends HelperEffect> = [E extends HelperEffect ? keyof E["fields"] : never] extends [never] ? [Extract<E["rows"], "nullable">] extends [never] ? unknown : RecordRows<"A helper cannot apply nullable to a query made by get, pluck, or an aggregate"> : RecordRows<"A helper cannot select fields on a query made by get, pluck, or an aggregate">;
+/** Constraint of a query whose rows are records, which a query of values fails with error `Message`. */
+interface RecordRows<Message extends string> {
+  readonly value: false | HelperError<Message>;
+}
+/** Schema context of a query that has the relations of its schema that a helper of effect `E` may read. */
+type ReadsContext<E extends HelperEffect> = [E["reads"]] extends [never] ? SchemaContext : SchemaContext<{ readonly [K in E["reads"]["key"]]: { readonly [N in Extract<E["reads"], {
+  readonly key: K;
+}>["name"]]: Extract<E["reads"], {
+  readonly key: K;
+  readonly name: N;
+}>["relation"]; }; }, E["key"]>;
+/** State of a query of state `S` after a helper of effect `E`. */
+type ApplyEffect<S extends SelectQueryState, E extends HelperEffect> = ChangeState<S, {
+  result: [keyof E["fields"]] extends [never] ? S["result"] : MergeSelection<S["result"], E["fields"]>;
+  rows: E["rows"] extends "many" ? EffectRows<S, E> : E["rows"] extends "one" ? OneRow<EffectRows<S, E>> : E["rows"];
+  uses: S["uses"] | E["uses"];
+  guaranteed: E["guaranteed"] extends true ? S["guaranteed"] : false;
+}>;
+/** Rows mode of a query of state `S` after a helper of effect `E` that keeps the rows, before `take`: relaxed as after a filter when the helper ends the guarantee. */
+type EffectRows<S extends SelectQueryState, E extends HelperEffect> = E["guaranteed"] extends true ? S["rows"] : FilteredStateRows<S>;
+/**
+ * Helper of `defineHelper` for queries over table `T`: it applies effect `E` to the query it receives with arguments `A` and returns a query of the same kind.
+ *
+ * Selected fields replace earlier fields under the same keys; a query made by `get`, `pluck`, or an aggregate method does not accept a helper that selects fields.
+ */
+type Helper<T extends AnyTable, E extends HelperEffect, A extends unknown[]> = <S extends HelperInput<T, E>, Kind extends SelectQueryKind>(query: SelectQuery<S, Kind>, ...args: A) => E extends HelperEffect ? SelectQuery<ApplyEffect<S, E>, Kind> : never;
+/**
+ * Defines a reusable helper of a table that filters, selects fields, and applies `take`, `optional`, `nullable`, and `required`, used with `use` or called with a query.
+ *
+ * `helper` receives the query it is applied to and any further arguments, and returns the query with its clauses.
+ * Defined with a query of a schema, such as `schema.form`, it can select the relations of the table in that schema, and applies to queries whose schema has them.
+ * The helper returns a query of the same kind as the one it is applied to, bound to the same `Db` if any.
+ */
+declare function defineHelper<T extends AnyTable, R extends SelectQuery<any, SelectQueryKind>, A extends unknown[], C extends SchemaContext = NoRelations>(table: TableOrQuery<T, C>, helper: (query: SelectQuery<HelperState<T, C>, SelectQueryKind>, ...args: A) => R & CheckResult<R["types"]>): Helper<T, ReadEffect<R["types"]>, A>;
+/** Tagged template building a SQL fragment of values `T` that accepts compared values `I`. */
+type SqlTemplate<T, O extends OperatorDefinitions, I = T> = (strings: TemplateStringsArray, ...values: unknown[]) => Expression<T, O, I>;
+/**
+ * Builds a SQL fragment.
+ *
+ * Interpolated expressions such as column references stay structured, a query of a table without clauses, such as `db.form`, becomes the name of the table, and other values become query parameters.
+ * The type argument declares the TypeScript type of the fragment and does not convert values at runtime, so the fragment cannot be selected; the fragment has `isNull` and the operators of `equalityOperators` only.
+ */
+declare function sql<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): UntypedExpression<T>;
+/**
+ * Creates a template building SQL fragments of `type`.
+ *
+ * The fragments have the operators of the type and encode compared values with it; the type adds no SQL cast.
+ */
+declare function sql<Output, Input, O extends OperatorDefinitions>(type: Type<Output, Input, O, any>): SqlTemplate<Output, O, Input>;
+/**
+ * Creates an expression of a query parameter encoded with a type, for a value interpolated into `sql` or compared on its own.
+ *
+ * With a type, the parameter is cast to it, such as `$1::integer`, so that PostgreSQL applies the operators of the type even where nothing else in the statement determines it.
+ * The cast omits type parameters, such as `$1::numeric` for `numeric(10,2)`, so that their precision, scale, or length do not constrain the value.
+ *
+ * With an expression, such as `param(self, other)` in an operator definition, the type of the expression encodes the value, and the parameter is not cast: PostgreSQL types it by the expression it is used with.
+ * `value` may then also be an expression, such as an operand of a generic operator, which is returned as it is, with its own type and nullability.
+ */
+declare function param<Output, Input, O extends OperatorDefinitions>(type: Type<Output, Input, O, any>, value: Input): Expression<Output, O, Input>;
+declare function param<E extends AnyExpression, V extends (E extends AnyExpression<infer T, infer I> ? Operand<T, I> : never)>(type: E, value: V): V extends AnyExpression ? V : E;
+export { HelperEffect as a, textOperators as c, Helper as i, orderingOperators as l, param as n, defineHelper as o, sql as r, PatternSignature as s, SqlTemplate as t };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { $ as one, $n as TextValue, $t as and, A as SqlQueryState, An as ColumnOperators, At as UpdateValues, B as RelationDeclaration, Bn as NotFoundError, Bt as orderBy, C as AnyQuery, Cn as Operand, Ct as ResultOf, D as FieldTypes, Dn as AnyTable, Dt as ColumnValue, E as DecodedFields, En as CompileOptions, Et as from, F as DeclaredRelations, Fn as Table, Ft as OrderTerms, G as RequiredMember, Gn as Connection, Gt as WhereCondition, H as RelationKey, Hn as ResultDecodeError, Ht as NotAKey, I as MergeRelations, In as TableKeys, It as Ordering, J as TableContext, Jn as SqlStatement, Jt as defineFilter, K as SchemaContext, Kn as Driver, Kt as WhereFilter, L as NoRelations, Ln as TableOptions, Lt as SelectedRefs, M as InitialMutationState, Mn as ColumnValues, Mt as OrderDirection, N as MutationQuery, Nn as KeyColumns, Nt as OrderKey, O as InitialSqlQueryState, On as AnyTableKeys, Ot as InsertValues, P as MutationQueryState, Pn as Selectable, Pt as OrderTerm, Q as many, Qn as BaseType, Qt as Predicate, R as OneRelationKeys, Rn as ToColumns, Rt as asc, Sn as ComparisonSignature, St as FilteredStateRows, T as AnySqlQuery, Tn as compare, U as RelationKeys, Un as ResultMode, Ut as PrimaryKeyValues, V as RelationDeclarations, Vn as RequiredRelationError, Vt as KeyCheck, W as RelationKind, Wn as ResultRows, Wt as EqValue, X as UsableRelation, Xn as createStatement, Xt as Condition, Y as TableRelations, Yn as TransactionFailure, Yt as CombinedCondition, Z as UsedRelation, Zn as AnyType, Zt as ConditionOperand, _n as EqualityOperators, _r as GenericOperatorImplementation, _t as SelectionResult, a as UntypedExpression, an as FilteredRows, ar as TypeTransform, at as Tables, bn as equalityOperators, bt as BoundSelectQuery, c as Db, cn as QueryResult, cr as Column, ct as RecordQuery, d as DbQueryState, dn as EmptyRecord, dr as ToColumn, dt as ExpressionInput, en as not, er as Type, et as AnySchema, f as Database, fn as InitialQueryState, fr as BoundOperators, ft as ExpressionValue, gn as EqualityOperator, gr as GenericOperator, gt as Selection, h as TransactionCoordinator, hn as SelectQueryState, hr as OperatorDefinitions, ht as NestedQuery, i as TypedExpression, in as RelationRefs, ir as TypeOutput, it as SchemaTables, j as AnyMutationQuery, jn as ColumnShape, jt as OrderColumns, k as SqlQuery, kn as ColumnDefinitions, kt as UpdateSet, l as DbMutationState, ln as ResultByRows, lr as ColumnAttributes, lt as RecordQueryState, m as createDatabase, mn as QueryStateOf, mr as NoOperators, mt as MergeSelection, n as BaseOperators, nn as ColumnRefs, nr as TypeOperators, nt as SchemaPart, o as AnyDb, on as OneRow, or as defineType, ot as defineSchema, p as DatabaseOptions, pn as QueryState, pr as MergeOperators, q as SchemaRelations, qn as DriverResult, qt as WhereValues, r as Expression, rn as QueryContext, rr as TypeOptions, rt as SchemaPartRelations, s as BindOptions, sn as OneValueRows, sr as AnyColumn, st as AnyRecordQuery, t as AnyExpression, tn as or, tr as TypeInput, tt as Schema, u as DbOf, un as ValueRows, ur as KeyKind, ut as SelectionState, vn as HasEquality, vr as OperatorSignature, vt as SelectionUses, w as SelectQueryKind, wn as OperandValue, wt as SelectQuery, xn as BooleanResult, yn as InSignature, yr as defineGenericOperator, yt as AnySelectQuery, z as Relation, zn as defineTable, zt as desc } from "./expression-Bc-s_0qJ.mjs";
+import { a as HelperEffect, c as textOperators, i as Helper, l as orderingOperators, n as param, o as defineHelper, r as sql, s as PatternSignature, t as SqlTemplate } from "./index-Chr-UK_t.mjs";
+export { type AnyColumn, type AnyDb, type AnyExpression, type AnyMutationQuery, type AnyQuery, type AnyRecordQuery, type AnySchema, type AnySelectQuery, type AnySqlQuery, type AnyTable, type AnyTableKeys, type AnyType, type BaseOperators, type BaseType, type BindOptions, type BooleanResult, type BoundOperators, type BoundSelectQuery, type Column, type ColumnAttributes, type ColumnDefinitions, type ColumnOperators, type ColumnRefs, type ColumnShape, type ColumnValue, type ColumnValues, type CombinedCondition, type ComparisonSignature, type CompileOptions, type Condition, type ConditionOperand, type Connection, type Database, type DatabaseOptions, type Db, type DbMutationState, type DbOf, type DbQueryState, type DeclaredRelations, type DecodedFields, type Driver, type DriverResult, type EmptyRecord, type EqValue, type EqualityOperator, type EqualityOperators, type Expression, type ExpressionInput, type ExpressionValue, type FieldTypes, type FilteredRows, type FilteredStateRows, type GenericOperator, type GenericOperatorImplementation, type HasEquality, type Helper, type HelperEffect, type InSignature, type InitialMutationState, type InitialQueryState, type InitialSqlQueryState, type InsertValues, type KeyCheck, type KeyColumns, type KeyKind, type MergeOperators, type MergeRelations, type MergeSelection, type MutationQuery, type MutationQueryState, type NestedQuery, type NoOperators, type NoRelations, type NotAKey, NotFoundError, type OneRelationKeys, type OneRow, type OneValueRows, type Operand, type OperandValue, type OperatorDefinitions, type OperatorSignature, type OrderColumns, type OrderDirection, type OrderKey, type OrderTerm, type OrderTerms, type Ordering, type PatternSignature, type Predicate, type PrimaryKeyValues, type QueryContext, type QueryResult, type QueryState, type QueryStateOf, type RecordQuery, type RecordQueryState, type Relation, type RelationDeclaration, type RelationDeclarations, type RelationKey, type RelationKeys, type RelationKind, type RelationRefs, type RequiredMember, RequiredRelationError, type ResultByRows, ResultDecodeError, type ResultMode, type ResultOf, type ResultRows, type Schema, type SchemaContext, type SchemaPart, type SchemaPartRelations, type SchemaRelations, type SchemaTables, type SelectQuery, type SelectQueryKind, type SelectQueryState, type Selectable, type SelectedRefs, type Selection, type SelectionResult, type SelectionState, type SelectionUses, type SqlQuery, type SqlQueryState, type SqlStatement, type SqlTemplate, type Table, type TableContext, type TableKeys, type TableOptions, type TableRelations, type Tables, type TextValue, type ToColumn, type ToColumns, type TransactionCoordinator, type TransactionFailure, type Type, type TypeInput, type TypeOperators, type TypeOptions, type TypeOutput, type TypeTransform, type TypedExpression, type UntypedExpression, type UpdateSet, type UpdateValues, type UsableRelation, type UsedRelation, type ValueRows, type WhereCondition, type WhereFilter, type WhereValues, and, asc, compare, createDatabase, createStatement, defineFilter, defineGenericOperator, defineHelper, defineSchema, defineTable, defineType, desc, equalityOperators, from, many, not, one, or, orderBy, orderingOperators, param, sql, textOperators };