@cleverbrush/knex-schema 0.0.0-beta-20260413145651

package/dist/mappers.d.ts

@@ -0,0 +1,61 @@
+import type { ValidatedSpec } from './types.js';
+/**
+ * Built-in named value mapper functions.
+ *
+ * Each entry maps a string key to a transformation function. Pass the key as
+ * the `mapper` argument to {@link mapValue} instead of a custom function.
+ *
+ * Currently available:
+ * - `date_from_json` — converts a JSON date string (`string | null`) to a
+ *   JavaScript `Date` object (or passes through falsy values unchanged).
+ */
+export declare const MAPPERS: Record<string, (value: any) => any>;
+/**
+ * Apply a single mapper to a value.
+ *
+ * @param mapper - Either a transformation function `(v: any) => any`, or a
+ *   string key referencing one of the {@link MAPPERS} built-ins (e.g.
+ *   `'date_from_json'`).
+ * @param value - The raw value to transform.
+ * @returns The transformed value.
+ *
+ * @throws If `mapper` is a string that does not exist in {@link MAPPERS}.
+ */
+export declare function mapValue(mapper: ((v: any) => any) | string, value: any): any;
+/**
+ * Apply a map of per-key transformations to an object, returning a new object
+ * with the transformed values.
+ *
+ * Keys not present in `mappers` are copied through unchanged. Keys present in
+ * `mappers` are passed through {@link mapValue}.
+ *
+ * @param obj - The source object (e.g. a raw database row).
+ * @param mappers - A `Record` mapping property keys to mapper functions or
+ *   {@link MAPPERS} built-in names.
+ * @returns A shallow copy of `obj` with the specified values transformed.
+ *
+ * @throws If `obj` is `null` or a non-object, it is returned as-is.
+ */
+export declare function mapObject<T extends Record<string, any>>(obj: T, mappers: Record<string, ((v: any) => any) | string>): T;
+/**
+ * Apply value mappers to the joined fields of a result row in place.
+ *
+ * After an eager-loaded query resolves, joined objects and arrays may contain
+ * raw database values that need transformation (e.g. date strings → `Date`).
+ * This function iterates over the one-to-one and one-to-many specs, applies
+ * the `mappers` defined on each spec to the nested data, and returns the
+ * mutated row.
+ *
+ * This is an internal helper used by {@link SchemaQueryBuilder}'s result
+ * mapping pipeline. Exported to allow custom post-processing if needed.
+ *
+ * @param row - The raw result row (mutated in place).
+ * @param oneSpecs - Validated one-to-one join specs with optional `mappers`.
+ * @param manySpecs - Validated one-to-many join specs with optional `mappers`.
+ * @returns The mutated `row` object.
+ */
+export declare function clearRow(row: Record<string, any>, oneSpecs: Array<ValidatedSpec & {
+    type: 'one';
+}>, manySpecs: Array<ValidatedSpec & {
+    type: 'many';
+}>): Record<string, any>;

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+import type { InferType, ObjectSchemaBuilder, PropertyDescriptor, PropertyDescriptorTree } from '@cleverbrush/schema';
+import type { Knex } from 'knex';
+export type SchemaKeys<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = keyof InferType<T> & string;
+/**
+ * Strips the `withExtensions()` overlay from a schema type, reducing it to a
+ * plain `ObjectSchemaBuilder<TProps, TReq>`. This is necessary so that
+ * `PropertyDescriptorTree<SchemaBase<T>, SchemaBase<T>>` resolves without
+ * hitting TypeScript's recursion depth limit, which happens when the full
+ * intersection type (builder + extension methods + HiddenExtensionMethods) is
+ * passed directly.
+ */
+type SchemaBase<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = T extends ObjectSchemaBuilder<infer P, infer Req, any, any, any, any, any> ? ObjectSchemaBuilder<P, Req> : never;
+export type ColumnRef<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = SchemaKeys<T> | ((tree: PropertyDescriptorTree<SchemaBase<T>, SchemaBase<T>>) => PropertyDescriptor<SchemaBase<T>, any, any>);
+export interface JoinOneSpec<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TFieldName extends string = string, TRequired extends boolean = true> {
+    /** Column on the local (base) table used for the join (string key or property accessor) */
+    localColumn: ColumnRef<TLocalSchema>;
+    /** Column on the foreign table used for the join (string key or property accessor) */
+    foreignColumn: ColumnRef<TForeignSchema>;
+    /** Name of the field that will hold the loaded object in the result */
+    as: TFieldName;
+    /** If true (default), uses INNER JOIN; if false, uses LEFT JOIN (result may be null) */
+    required?: TRequired;
+    /** Optional Knex query builder for the foreign table — auto-derived from foreignSchema's tableName if omitted */
+    foreignQuery?: Knex.QueryBuilder | {
+        toKnexQuery(): Knex.QueryBuilder;
+    };
+    /** Foreign schema for type inference */
+    foreignSchema: TForeignSchema;
+    /** Optional post-load value transformers per foreign column */
+    mappers?: Partial<Record<SchemaKeys<TForeignSchema>, ((value: any) => any) | string>>;
+}
+export interface JoinManySpec<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TFieldName extends string = string> {
+    /** Column on the local (base) table used for the join (string key or property accessor) */
+    localColumn: ColumnRef<TLocalSchema>;
+    /** Column on the foreign table used for the join (string key or property accessor) */
+    foreignColumn: ColumnRef<TForeignSchema>;
+    /** Name of the field that will hold the loaded array in the result */
+    as: TFieldName;
+    /** Optional Knex query builder for the foreign table — auto-derived from foreignSchema's tableName if omitted */
+    foreignQuery?: Knex.QueryBuilder | {
+        toKnexQuery(): Knex.QueryBuilder;
+    };
+    /** Foreign schema for type inference */
+    foreignSchema: TForeignSchema;
+    /** Maximum number of related items to load per parent row */
+    limit?: number;
+    /** Number of related items to skip per parent row */
+    offset?: number;
+    /** Column to order the related items by (required for deterministic limit/offset) */
+    orderBy?: {
+        column: ColumnRef<TForeignSchema>;
+        direction?: 'asc' | 'desc';
+    };
+    /** Optional post-load value transformers per foreign column */
+    mappers?: Partial<Record<SchemaKeys<TForeignSchema>, ((value: any) => any) | string>>;
+}
+/** Adds a single joined object field to TBase */
+export type WithJoinedOne<TBase, TFieldName extends string, TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TRequired extends boolean> = TBase & {
+    [K in TFieldName]: TRequired extends true ? InferType<TForeignSchema> : InferType<TForeignSchema> | null;
+};
+/** Adds a joined collection field to TBase */
+export type WithJoinedMany<TBase, TFieldName extends string, TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = TBase & {
+    [K in TFieldName]: InferType<TForeignSchema>[];
+};
+export interface ValidatedJoinOneSpec {
+    localColumn: string;
+    foreignColumn: string;
+    as: string;
+    required: boolean;
+    foreignQuery: Knex.QueryBuilder;
+    mappers?: Record<string, ((value: any) => any) | string>;
+}
+export interface ValidatedJoinManySpec {
+    localColumn: string;
+    foreignColumn: string;
+    as: string;
+    foreignQuery: Knex.QueryBuilder;
+    limit: number | null;
+    offset: number | null;
+    orderBy: {
+        column: string;
+        direction: 'asc' | 'desc';
+    } | null;
+    mappers?: Record<string, ((value: any) => any) | string>;
+}
+export type ValidatedSpec = ({
+    type: 'one';
+} & ValidatedJoinOneSpec) | ({
+    type: 'many';
+} & ValidatedJoinManySpec);
+export type InsertType<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = InferType<T>;
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import type { ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { Knex } from 'knex';
+import type { JoinManySpec, JoinOneSpec, ValidatedJoinManySpec, ValidatedJoinOneSpec } from './types.js';
+export declare function validateJoinOne(spec: JoinOneSpec<any, any, any, any>, localSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, knex: Knex): ValidatedJoinOneSpec;
+export declare function validateJoinMany(spec: JoinManySpec<any, any, any>, localSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, knex: Knex): ValidatedJoinManySpec;
+export declare function validateUniqueFieldNames(specs: Array<{
+    as: string;
+}>): void;

package/package.json

@@ -0,0 +1,52 @@
+{
+    "author": "Andrew Zolotukhin <andrew_zol@cleverbrush.com>",
+    "bugs": {
+        "url": "https://github.com/cleverbrush/framework/issues",
+        "email": "andrew_zol@cleverbrush.com"
+    },
+    "dependencies": {
+        "@cleverbrush/schema": "0.0.0-beta-20260413145651"
+    },
+    "peerDependencies": {
+        "knex": ">=3.1.0"
+    },
+    "description": "Type-safe schema-driven query builder for Knex using @cleverbrush/schema — strongly typed CRUD, eager loading, and column mapping for PostgreSQL",
+    "files": [
+        "dist"
+    ],
+    "homepage": "https://docs.cleverbrush.com/knex-schema",
+    "keywords": [
+        "knex",
+        "query builder",
+        "schema",
+        "typescript",
+        "type-safe",
+        "postgresql",
+        "orm",
+        "eager loading",
+        "cleverbrush"
+    ],
+    "license": "BSD 3-Clause",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "sideEffects": false,
+    "name": "@cleverbrush/knex-schema",
+    "readme": "https://github.com/cleverbrush/framework/tree/master/libs/knex-schema#readme",
+    "repository": {
+        "type": "git",
+        "url": "github:cleverbrush/framework"
+    },
+    "scripts": {
+        "watch": "tsc --build tsconfig.build.json --watch",
+        "build": "tsup && tsc --project tsconfig.build.json --emitDeclarationOnly",
+        "clean": "rm -rf dist tsconfig.build.tsbuildinfo"
+    },
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "version": "0.0.0-beta-20260413145651"
+}