kysely-hydrate 0.7.2 → 0.8.0

package/README.md

@@ -132,6 +132,7 @@ type Result = Array<{
   - [Inspect the SQL](#inspecting-the-sql)
   - [Mapped properties with `.mapFields()`](#mapped-properties-with-mapfields)
   - [Computed properties with `.extras()`](#computed-properties-with-extras)
+  - [Computed properties with `.extend()`](#computed-properties-with-extend)
   - [Excluded properties with `.omit()`](#excluded-properties-with-omit)
   - [Output transformations with `.map()`](#output-transformations-with-map)
   - [Composable mappings with `.with()`](#composable-mappings-with-with)
@@ -146,7 +147,7 @@ type Result = Array<{
   - [Output transformations with `.map()`](#output-transformations-with-map-1)
   - [Attached collections with `.attach*()`](#attached-collections-with-attach)
   - [Prefixed collections with `.has*()`](#prefixed-collections-with-has)
-  - [Composing hydrators with `.extend()`](#composing-hydrators-with-extend)
+  - [Composing hydrators with `.with()`](#composing-hydrators-with-with)
 - [FAQ](#faq)
 
 ## Installation
@@ -843,6 +844,34 @@ type Result = Array<{
 }>;
 ```
 
+### Computed properties with `.extend()`
+
+Like `.extras()`, but takes a single function that returns an object. All
+returned keys are merged into the output. This is useful when multiple computed
+fields share intermediate work.
+
+```ts
+const users = await querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "firstName", "lastName", "birthDate"]))
+	.extend((row) => {
+		const names = [row.firstName, row.lastName];
+		return {
+			fullName: names.join(" "),
+			initials: names.map((n) => n[0]).join(""),
+		};
+	})
+	.execute();
+// ⬇
+type Result = Array<{
+	id: number;
+	firstName: string;
+	lastName: string;
+	birthDate: Date;
+	fullName: string;
+	initials: string;
+}>;
+```
+
 ### Excluded properties with `.omit()`
 
 Remove fields from the final output. This is useful for removing intermediate
@@ -1355,7 +1384,7 @@ type Result = UserModel[];
 
 As in query sets, `.map()` is a terminal operation—after calling it, you can
 only call `.map()` again or `.hydrate()`. You cannot call configuration methods
-like `.fields()`, `.extras()`, `.has*()`, or `.extend()`.
+like `.fields()`, `.extras()`, `.has*()`, or `.with()`.
 
 ```ts
 const mapped = createHydrator<User>()
@@ -1368,7 +1397,7 @@ mapped.hydrate(rows);
 
 // ❌ These don't compile:
 mapped.fields({ ... });   // Error: Property 'fields' does not exist
-mapped.extend(...);       // Error: Property 'extend' does not exist
+mapped.with(...);         // Error: Property 'with' does not exist
 ```
 
 ### Attached collections with `.attach*()`
@@ -1423,7 +1452,7 @@ non-nullable column that was made nullable by a left join; or, (b) it's actually
 nullable in the "posts" table. The query set API, on the other hand, _does_
 know the difference, and so does not suffer from this problem.
 
-### Composing hydrators with `.extend()`
+### Composing hydrators with `.with()`
 
 Merges two hydrators. The second hydrator's configuration takes precedence.
 
@@ -1431,7 +1460,7 @@ This is a good way to build small, reusable hydrators (for a "user preview", a
 "user display name", etc.) and compose them.
 
 > [!NOTE]
-> Hydrators must have the same `keyBy`. If they don't, `.extend()` throws.
+> Hydrators must have the same `keyBy`. If they don't, `.with()` throws.
 
 ```ts
 type UserRow = { id: number; username: string; email: string };
@@ -1442,7 +1471,7 @@ const withDisplayName = createHydrator<UserRow>().extras({
 	displayName: (u) => `${u.username} <${u.email}>`,
 });
 
-const combined = base.extend(withDisplayName);
+const combined = base.with(withDisplayName);
 // ⬇
 type Result = Hydrator<UserRow, { id: number; username: string; displayName: string }>;
 ```

package/dist/{errors-EVqhxGJc.mjs → errors-CbAVHTlW.mjs}

@@ -76,12 +76,12 @@ var UnsupportedNodeTypeError = class extends KyselyHydrateError {
 	}
 };
 /**
-* Error thrown when attempting to extend a Hydrator with another Hydrator
+* Error thrown when composing a Hydrator with another Hydrator
 * that has a different keyBy configuration.
 */
 var KeyByMismatchError = class extends KyselyHydrateError {
 	constructor(thisKeyBy, otherKeyBy) {
-		super(`Cannot extend hydrators with different keyBy: ${thisKeyBy} vs ${otherKeyBy}`);
+		super(`Cannot compose hydrators with different keyBy: ${thisKeyBy} vs ${otherKeyBy}`);
 	}
 };
 /**

package/dist/experimental.mjs

@@ -1,4 +1,4 @@
-import { d as UnsupportedAliasNodeTypeError, f as UnsupportedNodeTypeError, m as WildcardSelectionError, p as UnsupportedTableAliasNodeTypeError, t as AmbiguousColumnReferenceError, u as UnexpectedSelectionTypeError } from "./errors-EVqhxGJc.mjs";
+import { d as UnsupportedAliasNodeTypeError, f as UnsupportedNodeTypeError, m as WildcardSelectionError, p as UnsupportedTableAliasNodeTypeError, t as AmbiguousColumnReferenceError, u as UnexpectedSelectionTypeError } from "./errors-CbAVHTlW.mjs";
 import * as k from "kysely";
 
 //#region src/experimental/mapped-expression.ts

package/dist/index.d.mts

@@ -101,6 +101,15 @@ type Extras<Input> = Record<string, (input: Input) => unknown>;
  * Uses the return type of each extra function.
  */
 type InferExtras<Input, E extends Extras<Input>> = { [K in keyof E]: ReturnType<E[K]> };
+/**
+ * An extender function that receives the full input and returns an object
+ * of computed properties to merge into the output.
+ */
+type Extender<Input> = (input: Input) => Record<string, unknown>;
+/**
+ * Infers the output type for an extender function.
+ */
+type InferExtender<Input, F extends Extender<Input>> = ReturnType<F>;
 /**
  * The mode of a collection.
  *
@@ -298,18 +307,29 @@ interface FullHydrator<Input, Output> extends MappedHydrator<Input, Output> {
    */
   extras<E extends Extras<Input>>(extras: E): FullHydrator<Input, Extend<Output, InferExtras<Input, E>>>;
   /**
-   * Extends this Hydrator with the configuration from another Hydrator.  The
+   * Adds computed fields to the hydrated output by spreading the return value
+   * of a function.  Unlike `.extras()` which defines one field at a time,
+   * `.extend()` calls a single function whose returned object is merged into
+   * the output.
+   *
+   * @param fn - A function that receives the input and returns an object of
+   *   computed properties
+   * @returns A new Hydrator with the extender applied
+   */
+  extend<F extends Extender<Input>>(fn: F): FullHydrator<Input, Extend<Output, InferExtender<Input, F>>>;
+  /**
+   * Composes this Hydrator with the configuration from another Hydrator.  The
    * other Hydrator's configuration takes precedence in case of conflicts.
    *
    * Both hydrators must have the same `keyBy`, and any overlapping fields
    * between the two input types must have compatible types.
    *
-   * @param other - The Hydrator to extend with
+   * @param other - The Hydrator to compose with
    * @returns A new Hydrator with merged configuration
    * @throws {KeyByMismatchError} If the keyBy configurations don't match
    */
-  extend<OtherInput extends Partial<Input>, OtherOutput>(other: FullHydrator<OtherInput, OtherOutput>): FullHydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
-  extend<OtherInput extends Partial<Input>, OtherOutput>(other: MappedHydrator<OtherInput, OtherOutput>): MappedHydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
+  with<OtherInput extends Partial<Input>, OtherOutput>(other: FullHydrator<OtherInput, OtherOutput>): FullHydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
+  with<OtherInput extends Partial<Input>, OtherOutput>(other: MappedHydrator<OtherInput, OtherOutput>): MappedHydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
   /**
    * Configures a nested collection that exists in the same query result. The
    * child data is expected to be prefixed in the input (e.g., `posts$$id`,
@@ -621,7 +641,7 @@ interface TWithBaseQuery<in out T extends TQuerySet, in out BaseQuery extends TQ
   Collections: T["Collections"];
   JoinedQuery: TJoinedQueryWithBaseQuery<T["BaseAlias"], T["JoinedQuery"], BaseQuery>;
   OrderableColumns: T["OrderableColumns"] | (keyof BaseQuery["O"] & string);
-  HydratedOutput: Flatten<Omit<RawExtend<BaseQuery["O"], T["HydratedOutput"]>, T["OmittedKeys"]>>;
+  HydratedOutput: T["IsMapped"] extends true ? T["HydratedOutput"] : Flatten<Omit<RawExtend<BaseQuery["O"], T["HydratedOutput"]>, T["OmittedKeys"]>>;
   OmittedKeys: T["OmittedKeys"];
 }
 interface TWithOutput<in out T extends TQuerySet, in out Output> {
@@ -1359,6 +1379,37 @@ interface QuerySet<in out T extends TQuerySet> extends MappedQuerySet<T> {
    * @returns A new HydratedQueryBuilder with the extras applied.
    */
   extras<E extends Extras<TInput<T>>>(extras: E): QuerySet<TWithExtendedOutput<T, InferExtras<TInput<T>, E>>>;
+  /**
+   * Adds computed fields to the hydrated output by spreading the return value
+   * of a function.  Unlike `.extras()` which defines one field at a time,
+   * `.extend()` calls a single function whose returned object is merged into
+   * the output.
+   *
+   * ### Examples
+   *
+   * ```ts
+   * const users = await querySet(db)
+   *   .selectAs("users", (eb) => eb.selectFrom("users").select(["users.id", "users.firstName", "users.lastName"]))
+   *   .extend((row) => ({
+   *     fullName: `${row.firstName} ${row.lastName}`,
+   *     initials: `${row.firstName[0]}${row.lastName[0]}`,
+   *   }))
+   *   .execute();
+   * // ⬇
+   * type Result = Array<{
+   *   id: number;
+   *   firstName: string;
+   *   lastName: string;
+   *   fullName: string;
+   *   initials: string;
+   * }>;
+   * ```
+   *
+   * @param fn - A function that receives the row and returns an object of
+   *   computed properties.
+   * @returns A new HydratedQueryBuilder with the extender applied.
+   */
+  extend<F extends Extender<TInput<T>>>(fn: F): QuerySet<TWithExtendedOutput<T, InferExtender<TInput<T>, F>>>;
   /**
    * Transforms already-selected field values in the hydrated output.  Fields
    * not mentioned in the mappings will still be included as-is.
@@ -2581,7 +2632,7 @@ declare class UnsupportedNodeTypeError extends KyselyHydrateError {
   constructor(kind: string);
 }
 /**
- * Error thrown when attempting to extend a Hydrator with another Hydrator
+ * Error thrown when composing a Hydrator with another Hydrator
  * that has a different keyBy configuration.
  */
 declare class KeyByMismatchError extends KyselyHydrateError {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as KeyByMismatchError, c as UnexpectedComplexAliasError, d as UnsupportedAliasNodeTypeError, f as UnsupportedNodeTypeError, i as InvalidJoinedQuerySetError, l as UnexpectedSelectAllError, m as WildcardSelectionError, n as CardinalityViolationError, o as KyselyHydrateError, p as UnsupportedTableAliasNodeTypeError, r as ExpectedOneItemError, s as UnexpectedCaseError, t as AmbiguousColumnReferenceError, u as UnexpectedSelectionTypeError } from "./errors-EVqhxGJc.mjs";
+import { a as KeyByMismatchError, c as UnexpectedComplexAliasError, d as UnsupportedAliasNodeTypeError, f as UnsupportedNodeTypeError, i as InvalidJoinedQuerySetError, l as UnexpectedSelectAllError, m as WildcardSelectionError, n as CardinalityViolationError, o as KyselyHydrateError, p as UnsupportedTableAliasNodeTypeError, r as ExpectedOneItemError, s as UnexpectedCaseError, t as AmbiguousColumnReferenceError, u as UnexpectedSelectionTypeError } from "./errors-CbAVHTlW.mjs";
 import * as k from "kysely";
 
 //#region src/helpers/order-by.ts
@@ -264,7 +264,13 @@ var HydratorImpl = class HydratorImpl {
 			extras: addObjectToMap(this.#props.extras, extras)
 		});
 	}
-	extend(other) {
+	extend(fn) {
+		return new HydratorImpl({
+			...this.#props,
+			extenders: [...this.#props.extenders ?? [], fn]
+		});
+	}
+	with(other) {
 		const otherImpl = other;
 		const thisKeyBy = JSON.stringify(this.#props.keyBy);
 		const otherKeyBy = JSON.stringify(otherImpl.#props.keyBy);
@@ -276,6 +282,7 @@ var HydratorImpl = class HydratorImpl {
 			keyBy: otherProps.keyBy,
 			fields: new Map([...ownProps.fields ?? [], ...otherProps.fields ?? []]),
 			extras: new Map([...ownProps.extras ?? [], ...otherProps.extras ?? []]),
+			extenders: [...ownProps.extenders ?? [], ...otherProps.extenders ?? []],
 			collections: mergedCollections,
 			attachedCollections: new Map([...ownProps.attachedCollections ?? [], ...otherProps.attachedCollections ?? []]),
 			mapFns: [...this.#props.mapFns ?? [], ...otherProps.mapFns ?? []],
@@ -412,7 +419,7 @@ var HydratorImpl = class HydratorImpl {
 	* Hydrates a single entity. All attach collections are already fetched and provided in attachedDataMap.
 	*/
 	#hydrateOne(ctx, prefix, input, inputRows) {
-		const { fields, extras, collections, attachedCollections } = this.#props;
+		const { fields, extras, extenders, collections, attachedCollections } = this.#props;
 		const entity = {};
 		if (ctx.autoIncludeFields) for (const key of this.#getAutoFields(ctx, prefix, input)) entity[key] = getPrefixedValue(prefix, input, key);
 		if (fields) for (const [key, field] of fields) {
@@ -420,9 +427,10 @@ var HydratorImpl = class HydratorImpl {
 			const value = getPrefixedValue(prefix, input, key);
 			entity[key] = field === true ? value : field(value);
 		}
-		if (extras) {
+		if (extras || extenders) {
 			const accessor = createdPrefixedAccessor(prefix, input);
-			for (const [key, extra] of extras) entity[key] = extra(accessor);
+			if (extras) for (const [key, extra] of extras) entity[key] = extra(accessor);
+			if (extenders) for (const extender of extenders) Object.assign(entity, extender(accessor));
 		}
 		if (collections) {
 			const childCtx = this.#props.hasMultipleManyCollections && !ctx.hasSiblingManyCollections ? {
@@ -878,6 +886,9 @@ var QuerySetImpl = class QuerySetImpl {
 	extras(extras) {
 		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).extras(extras) });
 	}
+	extend(fn) {
+		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).extend(fn) });
+	}
 	mapFields(mappings) {
 		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).fields(mappings) });
 	}
@@ -885,7 +896,7 @@ var QuerySetImpl = class QuerySetImpl {
 		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).omit(keys) });
 	}
 	with(hydrator) {
-		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).extend(hydrator) });
+		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).with(hydrator) });
 	}
 	#addAttach(mode, key, fetchFn, keys) {
 		return this.#clone({ hydrator: asFullHydrator(this.#props.hydrator).attach(mode, key, fetchFn, keys) });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kysely-hydrate",
-	"version": "0.7.2",
+	"version": "0.8.0",
 	"description": "Explicit ORM-style queries with Kysely",
 	"homepage": "https://github.com/GiacoCorsiglia/kysely-hydrate#readme",
 	"bugs": {