@proseql/core 0.1.0

package/dist/operations/query/select.d.ts

@@ -0,0 +1,54 @@
+import type { UnknownRecord } from "../../types/types";
+/**
+ * Type helper to handle object-based field selections with nested support
+ */
+type SelectedTypeFromObject<T, Selection extends Record<string, unknown>> = {
+    [K in keyof Selection & keyof T]: Selection[K] extends true ? T[K] : Selection[K] extends Record<string, unknown> ? T[K] extends Record<string, unknown> ? SelectedTypeFromObject<T[K], Selection[K]> : never : never;
+};
+/**
+ * Apply object-based field selection to a single object
+ * @param data - The object to select fields from
+ * @param selection - Object with true values for fields to select
+ * @returns Object with only the selected fields
+ */
+export declare function applyObjectSelection<T extends UnknownRecord, const Selection extends Record<string, unknown>>(data: T, selection: Selection): SelectedTypeFromObject<T, Selection>;
+/**
+ * Apply field selection to an array of objects
+ * @param data - Array of objects to select fields from
+ * @param selection - Object with true values for fields to select
+ * @returns Array of objects with only the selected fields
+ */
+export declare function applySelectionToArray<T extends UnknownRecord, const Selection extends Record<string, unknown>>(data: T[], selection: Selection): Array<SelectedTypeFromObject<T, Selection>>;
+/**
+ * Apply field selection with null/undefined handling
+ * @param data - The object to select fields from (can be null/undefined)
+ * @param selection - Object with true values for fields to select
+ * @returns Object with selected fields or null/undefined
+ */
+export declare function applySelectionSafe<T extends UnknownRecord, const Selection extends Record<string, unknown>>(data: T | null | undefined, selection: Selection): SelectedTypeFromObject<T, Selection> | null | undefined;
+/**
+ * Check if a field should be selected based on selection criteria
+ * @param field - The field name to check
+ * @param selection - Object with true values or undefined for all fields
+ * @returns Whether the field should be included
+ */
+export declare function shouldSelectField<T extends UnknownRecord>(field: keyof T, selection: Record<string, unknown> | undefined): boolean;
+/**
+ * Type guard to check if a value has selected fields
+ */
+export declare function hasSelectedFields<T extends UnknownRecord, const Selection extends Record<string, unknown>>(value: unknown, selection: Selection): value is SelectedTypeFromObject<T, Selection>;
+/**
+ * Merge object-based field selections from multiple sources
+ * Useful for combining field selections from different query parts
+ */
+export declare function mergeObjectFieldSelections<_T extends UnknownRecord>(...selections: Array<Record<string, unknown> | undefined>): Record<string, unknown> | undefined;
+/**
+ * Create a field selector function for use in pipelines
+ */
+export declare function createFieldSelector<T extends UnknownRecord, const Selection extends Record<string, unknown>>(selection: Selection): (data: T) => SelectedTypeFromObject<T, Selection>;
+/**
+ * Create a field selector for arrays
+ */
+export declare function createArrayFieldSelector<T extends UnknownRecord, const Selection extends Record<string, unknown>>(selection: Selection): (data: T[]) => Array<SelectedTypeFromObject<T, Selection>>;
+export {};
+//# sourceMappingURL=select.d.ts.map

package/dist/operations/query/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/operations/query/select.ts"],"names":[],"mappings":"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"}

package/dist/operations/query/select.js

@@ -0,0 +1,159 @@
+// Type guard for checking if value is a record
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Type guard for checking if value is a UnknownRecord
+function isUnknownRecord(value) {
+    return isRecord(value);
+}
+// Type guard for checking if value is a selection config
+function isSelectionConfig(value) {
+    return isRecord(value);
+}
+/**
+ * Apply object-based field selection to a single object
+ * @param data - The object to select fields from
+ * @param selection - Object with true values for fields to select
+ * @returns Object with only the selected fields
+ */
+export function applyObjectSelection(data, selection) {
+    // Handle edge cases
+    if (!isUnknownRecord(data)) {
+        // Return empty object for invalid data
+        return {};
+    }
+    // If no selection specified, return empty object
+    if (!selection || Object.keys(selection).length === 0) {
+        return {};
+    }
+    // Create new object with only selected fields
+    const result = {};
+    for (const [key, value] of Object.entries(selection)) {
+        if (value === true && key in data) {
+            result[key] = data[key];
+        }
+        else if (isSelectionConfig(value) && key in data) {
+            // Handle nested selection for populated fields
+            const nestedData = data[key];
+            if (Array.isArray(nestedData)) {
+                result[key] = nestedData
+                    .filter(isUnknownRecord)
+                    .map((item) => applyObjectSelection(item, value));
+            }
+            else if (isUnknownRecord(nestedData)) {
+                result[key] = applyObjectSelection(nestedData, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Apply field selection to an array of objects
+ * @param data - Array of objects to select fields from
+ * @param selection - Object with true values for fields to select
+ * @returns Array of objects with only the selected fields
+ */
+export function applySelectionToArray(data, selection) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data.map((item) => applyObjectSelection(item, selection));
+}
+/**
+ * Apply field selection with null/undefined handling
+ * @param data - The object to select fields from (can be null/undefined)
+ * @param selection - Object with true values for fields to select
+ * @returns Object with selected fields or null/undefined
+ */
+export function applySelectionSafe(data, selection) {
+    if (data === null)
+        return null;
+    if (data === undefined)
+        return undefined;
+    return applyObjectSelection(data, selection);
+}
+/**
+ * Check if a field should be selected based on selection criteria
+ * @param field - The field name to check
+ * @param selection - Object with true values or undefined for all fields
+ * @returns Whether the field should be included
+ */
+export function shouldSelectField(field, selection) {
+    // If no selection specified, include all fields
+    if (!selection) {
+        return true;
+    }
+    // Handle object-based selection
+    const fieldStr = String(field);
+    return fieldStr in selection && selection[fieldStr] === true;
+}
+/**
+ * Type guard to check if a value has selected fields
+ */
+export function hasSelectedFields(value, selection) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    if (!isUnknownRecord(value)) {
+        return false;
+    }
+    const obj = value;
+    // Handle object-based selection
+    return Object.entries(selection).every(([key, val]) => {
+        if (val === true) {
+            return key in obj;
+        }
+        return true; // Skip non-true values
+    });
+}
+/**
+ * Merge object-based field selections from multiple sources
+ * Useful for combining field selections from different query parts
+ */
+export function mergeObjectFieldSelections(...selections) {
+    // Filter out undefined selections
+    const validSelections = selections.filter((sel) => sel !== undefined);
+    // If no valid selections, return undefined (select all)
+    if (validSelections.length === 0) {
+        return undefined;
+    }
+    // Merge all selections with deep merge for nested objects
+    const merged = {};
+    for (const selection of validSelections) {
+        for (const [key, value] of Object.entries(selection)) {
+            if (value === true) {
+                merged[key] = true;
+            }
+            else if (typeof value === "object" && value !== null) {
+                // Deep merge nested selections
+                const existing = merged[key];
+                if (typeof existing === "object" &&
+                    existing !== null &&
+                    !Array.isArray(existing)) {
+                    merged[key] = { ...existing, ...value };
+                }
+                else {
+                    merged[key] = { ...value };
+                }
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Create a field selector function for use in pipelines
+ */
+export function createFieldSelector(selection) {
+    return (data) => {
+        return applyObjectSelection(data, selection);
+    };
+}
+/**
+ * Create a field selector for arrays
+ */
+export function createArrayFieldSelector(selection) {
+    return (data) => {
+        return applySelectionToArray(data, selection);
+    };
+}
+//# sourceMappingURL=select.js.map

package/dist/operations/query/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/operations/query/select.ts"],"names":[],"mappings":"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"}

package/dist/operations/query/sort-stream.d.ts

@@ -0,0 +1,46 @@
+import { Stream } from "effect";
+import { SEARCH_SCORE_KEY, type SearchConfig } from "../../types/search-types.js";
+/**
+ * A sort configuration mapping field names to sort direction.
+ */
+type SortConfig = Partial<Record<string, "asc" | "desc">>;
+/**
+ * Extract SearchConfig from a where clause if present at top level.
+ * Returns undefined if no top-level $search is found.
+ */
+export declare function extractSearchConfig(where: Record<string, unknown> | undefined): SearchConfig | undefined;
+/**
+ * Compute and attach search relevance scores as metadata to each item in the stream.
+ * This is called after filtering to pre-compute scores for the sort stage.
+ *
+ * Attaches the score as `_searchScore` on each item. Items that don't match
+ * the search (already filtered out) won't be processed.
+ *
+ * @param searchConfig - The search configuration containing query and optional fields
+ * @returns A stream combinator that attaches _searchScore metadata to each item
+ */
+export declare const attachSearchScores: <T extends Record<string, unknown>>(searchConfig: SearchConfig | undefined) => <E, R>(stream: Stream.Stream<T, E, R>) => Stream.Stream<T & {
+    readonly [SEARCH_SCORE_KEY]?: number;
+}, E, R>;
+/**
+ * Apply relevance-based sorting for search results.
+ * Sorts items by their search relevance score in descending order.
+ *
+ * This function expects items to have a pre-computed `_searchScore` attached
+ * by `attachSearchScores`. If the score is not present, it falls back to
+ * computing the score on-the-fly.
+ *
+ * @param searchConfig - The search configuration containing query and optional fields
+ * @returns A stream combinator that sorts by relevance score
+ */
+export declare const applyRelevanceSort: <T extends Record<string, unknown>>(searchConfig: SearchConfig) => <E, R>(stream: Stream.Stream<T, E, R>) => Stream.Stream<T, E, R>;
+/**
+ * Apply a sort configuration as a Stream combinator.
+ * Collects the stream, sorts in memory, and re-emits as a new stream.
+ *
+ * Supports multi-field sorting with asc/desc order, nested field paths (dot notation),
+ * and handles undefined/null values (sorted to the end regardless of direction).
+ */
+export declare const applySort: <T extends Record<string, unknown>>(sort: SortConfig | undefined) => <E, R>(stream: Stream.Stream<T, E, R>) => Stream.Stream<T, E, R>;
+export {};
+//# sourceMappingURL=sort-stream.d.ts.map

package/dist/operations/query/sort-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort-stream.d.ts","sourceRoot":"","sources":["../../../src/operations/query/sort-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EACN,gBAAgB,EAChB,KAAK,YAAY,EACjB,MAAM,6BAA6B,CAAC;AAIrC;;GAEG;AACH,KAAK,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,YAAY,GAAG,SAAS,CAQ1B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,YAAY,GAAG,SAAS,MACzE,CAAC,EAAE,CAAC,EACJ,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EAAE,CAAC,CAiClE,CAAC;AAmCH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,YAAY,MAC7D,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAoC5D,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,UAAU,GAAG,SAAS,MAC/D,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAiC5D,CAAC"}

package/dist/operations/query/sort-stream.js

@@ -0,0 +1,158 @@
+import { Chunk, Effect, Stream } from "effect";
+import { SEARCH_SCORE_KEY, } from "../../types/search-types.js";
+import { getNestedValue } from "../../utils/nested-path.js";
+import { computeSearchScore, tokenize } from "./search.js";
+/**
+ * Extract SearchConfig from a where clause if present at top level.
+ * Returns undefined if no top-level $search is found.
+ */
+export function extractSearchConfig(where) {
+    if (!where)
+        return undefined;
+    const searchValue = where.$search;
+    if (searchValue === null || typeof searchValue !== "object")
+        return undefined;
+    const config = searchValue;
+    // Validate that it has the required 'query' property
+    if (typeof config.query !== "string")
+        return undefined;
+    return config;
+}
+/**
+ * Compute and attach search relevance scores as metadata to each item in the stream.
+ * This is called after filtering to pre-compute scores for the sort stage.
+ *
+ * Attaches the score as `_searchScore` on each item. Items that don't match
+ * the search (already filtered out) won't be processed.
+ *
+ * @param searchConfig - The search configuration containing query and optional fields
+ * @returns A stream combinator that attaches _searchScore metadata to each item
+ */
+export const attachSearchScores = (searchConfig) => (stream) => {
+    // No search config: pass through unchanged (no scores to attach)
+    if (!searchConfig)
+        return stream;
+    const queryTokens = tokenize(searchConfig.query);
+    // Empty query: no scoring needed
+    if (queryTokens.length === 0)
+        return stream;
+    return Stream.map(stream, (item) => {
+        // Determine target fields: explicit or all string fields
+        let targetFields;
+        if (searchConfig.fields && searchConfig.fields.length > 0) {
+            targetFields = searchConfig.fields;
+        }
+        else {
+            targetFields = Object.keys(item).filter((k) => typeof item[k] === "string");
+        }
+        const score = computeSearchScore(item, queryTokens, targetFields);
+        return { ...item, [SEARCH_SCORE_KEY]: score };
+    });
+};
+/**
+ * Compare two values for sorting, returning a negative, zero, or positive number.
+ * Handles undefined/null (always sort to end), strings, numbers, booleans, Dates, and fallback toString.
+ */
+function compareValues(aValue, bValue) {
+    // Handle undefined/null values - they always sort to the end
+    if (aValue === undefined || aValue === null) {
+        if (bValue === undefined || bValue === null) {
+            return 0;
+        }
+        return 1;
+    }
+    if (bValue === undefined || bValue === null) {
+        return -1;
+    }
+    if (typeof aValue === "string" && typeof bValue === "string") {
+        return aValue.localeCompare(bValue);
+    }
+    if (typeof aValue === "number" && typeof bValue === "number") {
+        return aValue - bValue;
+    }
+    if (typeof aValue === "boolean" && typeof bValue === "boolean") {
+        return (aValue ? 1 : 0) - (bValue ? 1 : 0);
+    }
+    if (aValue instanceof Date && bValue instanceof Date) {
+        return aValue.getTime() - bValue.getTime();
+    }
+    // Fallback: convert to string
+    return String(aValue).localeCompare(String(bValue));
+}
+/**
+ * Apply relevance-based sorting for search results.
+ * Sorts items by their search relevance score in descending order.
+ *
+ * This function expects items to have a pre-computed `_searchScore` attached
+ * by `attachSearchScores`. If the score is not present, it falls back to
+ * computing the score on-the-fly.
+ *
+ * @param searchConfig - The search configuration containing query and optional fields
+ * @returns A stream combinator that sorts by relevance score
+ */
+export const applyRelevanceSort = (searchConfig) => (stream) => {
+    const queryTokens = tokenize(searchConfig.query);
+    // Empty query: no relevance to sort by
+    if (queryTokens.length === 0)
+        return stream;
+    return Stream.unwrap(Effect.map(Stream.runCollect(stream), (chunk) => {
+        const arr = Chunk.toArray(chunk);
+        // Sort by pre-computed score, or compute on-the-fly if not present
+        const scored = arr.map((item) => {
+            // Use pre-computed score if available
+            const preComputedScore = item[SEARCH_SCORE_KEY];
+            if (typeof preComputedScore === "number") {
+                return { item, score: preComputedScore };
+            }
+            // Fallback: compute score on-the-fly (for backward compatibility)
+            let targetFields;
+            if (searchConfig.fields && searchConfig.fields.length > 0) {
+                targetFields = searchConfig.fields;
+            }
+            else {
+                targetFields = Object.keys(item).filter((k) => typeof item[k] === "string");
+            }
+            const score = computeSearchScore(item, queryTokens, targetFields);
+            return { item, score };
+        });
+        // Sort by score descending (higher scores first)
+        scored.sort((a, b) => b.score - a.score);
+        return Stream.fromIterable(scored.map(({ item }) => item));
+    }));
+};
+/**
+ * Apply a sort configuration as a Stream combinator.
+ * Collects the stream, sorts in memory, and re-emits as a new stream.
+ *
+ * Supports multi-field sorting with asc/desc order, nested field paths (dot notation),
+ * and handles undefined/null values (sorted to the end regardless of direction).
+ */
+export const applySort = (sort) => (stream) => {
+    if (!sort || Object.keys(sort).length === 0)
+        return stream;
+    const sortFields = Object.entries(sort);
+    return Stream.unwrap(Effect.map(Stream.runCollect(stream), (chunk) => {
+        const arr = Chunk.toArray(chunk);
+        arr.sort((a, b) => {
+            for (const [field, order] of sortFields) {
+                const aValue = getNestedValue(a, field);
+                const bValue = getNestedValue(b, field);
+                // Undefined/null always sort to the end, regardless of direction
+                const aIsNullish = aValue === undefined || aValue === null;
+                const bIsNullish = bValue === undefined || bValue === null;
+                if (aIsNullish || bIsNullish) {
+                    if (aIsNullish && bIsNullish)
+                        continue;
+                    return aIsNullish ? 1 : -1;
+                }
+                const comparison = compareValues(aValue, bValue);
+                if (comparison !== 0) {
+                    return order === "desc" ? -comparison : comparison;
+                }
+            }
+            return 0;
+        });
+        return Stream.fromIterable(arr);
+    }));
+};
+//# sourceMappingURL=sort-stream.js.map

package/dist/operations/query/sort-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort-stream.js","sourceRoot":"","sources":["../../../src/operations/query/sort-stream.ts"],"names":[],"mappings":"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"}

package/dist/operations/query/sort.d.ts

@@ -0,0 +1,9 @@
+import type { SortOrder } from "../../types/types";
+/**
+ * Sort an array of data based on sort configuration
+ * @param data The data to sort
+ * @param sortConfig The sort configuration (field -> order mapping)
+ * @returns The sorted data
+ */
+export declare function sortData<T extends Record<string, unknown>>(data: T[], sortConfig?: Partial<Record<string, SortOrder>>): T[];
+//# sourceMappingURL=sort.d.ts.map

package/dist/operations/query/sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.d.ts","sourceRoot":"","sources":["../../../src/operations/query/sort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAC7C,CAAC,EAAE,CAsDL"}

package/dist/operations/query/sort.js

@@ -0,0 +1,58 @@
+import { getNestedValue } from "../../utils/nested-path";
+/**
+ * Sort an array of data based on sort configuration
+ * @param data The data to sort
+ * @param sortConfig The sort configuration (field -> order mapping)
+ * @returns The sorted data
+ */
+export function sortData(data, sortConfig) {
+    if (!sortConfig || Object.keys(sortConfig).length === 0) {
+        return data;
+    }
+    // Create a copy to avoid mutating the original array
+    const sorted = [...data];
+    // Get sort fields in order
+    const sortFields = Object.entries(sortConfig);
+    sorted.sort((a, b) => {
+        for (const [field, order] of sortFields) {
+            const aValue = getNestedValue(a, field);
+            const bValue = getNestedValue(b, field);
+            // Handle undefined/null values - they always sort to the end
+            if (aValue === undefined || aValue === null) {
+                if (bValue === undefined || bValue === null) {
+                    continue; // Both undefined/null, check next field
+                }
+                return 1; // a is undefined/null, b is not - a goes after b
+            }
+            if (bValue === undefined || bValue === null) {
+                return -1; // b is undefined/null, a is not - a goes before b
+            }
+            // Compare values
+            let comparison = 0;
+            if (typeof aValue === "string" && typeof bValue === "string") {
+                comparison = aValue.localeCompare(bValue);
+            }
+            else if (typeof aValue === "number" && typeof bValue === "number") {
+                comparison = aValue - bValue;
+            }
+            else if (typeof aValue === "boolean" && typeof bValue === "boolean") {
+                // false < true in ascending order
+                comparison = (aValue ? 1 : 0) - (bValue ? 1 : 0);
+            }
+            else if (aValue instanceof Date && bValue instanceof Date) {
+                comparison = aValue.getTime() - bValue.getTime();
+            }
+            else {
+                // For other types, convert to string for comparison
+                comparison = String(aValue).localeCompare(String(bValue));
+            }
+            // Apply sort order
+            if (comparison !== 0) {
+                return order === "desc" ? -comparison : comparison;
+            }
+        }
+        return 0; // All fields are equal
+    });
+    return sorted;
+}
+//# sourceMappingURL=sort.js.map

package/dist/operations/query/sort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.js","sourceRoot":"","sources":["../../../src/operations/query/sort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACvB,IAAS,EACT,UAA+C;IAE/C,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,qDAAqD;IACrD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAEzB,2BAA2B;IAC3B,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE9C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAExC,6DAA6D;YAC7D,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC7C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;oBAC7C,SAAS,CAAC,wCAAwC;gBACnD,CAAC;gBACD,OAAO,CAAC,CAAC,CAAC,iDAAiD;YAC5D,CAAC;YACD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC7C,OAAO,CAAC,CAAC,CAAC,CAAC,kDAAkD;YAC9D,CAAC;YAED,iBAAiB;YACjB,IAAI,UAAU,GAAG,CAAC,CAAC;YAEnB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC9D,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;iBAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACrE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;YAC9B,CAAC;iBAAM,IAAI,OAAO,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,SAAS,EAAE,CAAC;gBACvE,kCAAkC;gBAClC,UAAU,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClD,CAAC;iBAAM,IAAI,MAAM,YAAY,IAAI,IAAI,MAAM,YAAY,IAAI,EAAE,CAAC;gBAC7D,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACP,oDAAoD;gBACpD,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC3D,CAAC;YAED,mBAAmB;YACnB,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;gBACtB,OAAO,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;YACpD,CAAC;QACF,CAAC;QAED,OAAO,CAAC,CAAC,CAAC,uBAAuB;IAClC,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/operations/relationships/populate-stream.d.ts

@@ -0,0 +1,29 @@
+import { Ref, Stream } from "effect";
+import { DanglingReferenceError } from "../../errors/query-errors.js";
+import type { CollectionConfig } from "../../types/database-config-types.js";
+/**
+ * PopulateValue can be:
+ * - `true` to populate a relationship with all fields
+ * - An object with nested populate config for recursive population
+ */
+type PopulateValue = boolean | Record<string, unknown>;
+/**
+ * Apply relationship population as a Stream combinator.
+ *
+ * For each item in the stream, resolves relationships by reading related
+ * entities from collection Refs. Supports nested population recursively
+ * up to a depth of 5.
+ *
+ * - `ref` relationships: look up a single entity in the target collection
+ *   using the foreign key field (default: `<relationName>Id`)
+ * - `inverse` relationships: find all entities in the target collection
+ *   whose foreign key points back to this item's `id`
+ *
+ * @param populateConfig - Which relationships to populate (e.g. `{ company: true }`)
+ * @param stateRefs - Map of collection name → Ref<ReadonlyMap<string, entity>>
+ * @param dbConfig - Full database config with relationship definitions
+ * @param collectionName - Name of the source collection being queried
+ */
+export declare const applyPopulate: <T extends Record<string, unknown>>(populateConfig: Record<string, PopulateValue> | undefined, stateRefs: Record<string, Ref.Ref<ReadonlyMap<string, Record<string, unknown>>>>, dbConfig: Record<string, CollectionConfig>, collectionName: string) => <E, R>(stream: Stream.Stream<T, E, R>) => Stream.Stream<T, E | DanglingReferenceError, R>;
+export {};
+//# sourceMappingURL=populate-stream.d.ts.map

package/dist/operations/relationships/populate-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"populate-stream.d.ts","sourceRoot":"","sources":["../../../src/operations/relationships/populate-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,GAAG,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAO7E;;;;GAIG;AACH,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAuMvD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GACxB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,gBAAgB,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,EACzD,WAAW,MAAM,CAChB,MAAM,EACN,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CACrD,EACD,UAAU,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC1C,gBAAgB,MAAM,MAEtB,CAAC,EAAE,CAAC,EACJ,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,sBAAsB,EAAE,CAAC,CAyBhD,CAAC"}