@proseql/core 0.1.0

package/dist/operations/query/resolve-computed.js

@@ -0,0 +1,197 @@
+import { Stream } from "effect";
+/**
+ * Resolve computed fields for a single entity.
+ *
+ * Iterates over the computed config, calling each derivation function with the entity,
+ * and returns a new object with the original entity fields plus computed field values.
+ *
+ * @template T - The entity type (stored fields, possibly with populated relationships)
+ * @template C - The computed fields config type
+ *
+ * @param entity - The entity to resolve computed fields for
+ * @param config - The computed fields configuration (field name → derivation function)
+ * @returns A new object with entity fields plus computed fields attached
+ *
+ * @example
+ * ```ts
+ * const book = { id: "1", title: "Dune", year: 1965 }
+ * const config = {
+ *   displayName: (b) => `${b.title} (${b.year})`,
+ *   isClassic: (b) => b.year < 1980,
+ * }
+ * const result = resolveComputedFields(book, config)
+ * // { id: "1", title: "Dune", year: 1965, displayName: "Dune (1965)", isClassic: true }
+ * ```
+ */
+export const resolveComputedFields = (entity, config) => {
+    const computedValues = {};
+    for (const key of Object.keys(config)) {
+        const derivationFn = config[key];
+        if (typeof derivationFn === "function") {
+            computedValues[key] = derivationFn(entity);
+        }
+    }
+    return { ...entity, ...computedValues };
+};
+/**
+ * Apply computed field resolution as a Stream combinator.
+ * Returns a function that transforms Stream<T> → Stream<WithComputed<T, C>>,
+ * mapping the resolution function over each entity.
+ *
+ * When the config is undefined or has no keys, returns the stream unchanged
+ * (no resolution overhead).
+ *
+ * @template T - The entity type (stored fields, possibly with populated relationships)
+ * @template C - The computed fields config type
+ *
+ * @param config - The computed fields configuration (field name → derivation function), or undefined
+ * @returns A stream combinator function
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   displayName: (b) => `${b.title} (${b.year})`,
+ *   isClassic: (b) => b.year < 1980,
+ * }
+ * const enrichedStream = stream.pipe(resolveComputedStream(config))
+ * // Each entity in the resulting stream has displayName and isClassic attached
+ * ```
+ */
+export const resolveComputedStream = (config) => (stream) => {
+    // When config is empty or undefined, return stream unchanged
+    if (config === undefined || Object.keys(config).length === 0) {
+        return stream;
+    }
+    return Stream.map(stream, (entity) => resolveComputedFields(entity, config));
+};
+/**
+ * Strip computed field keys from an entity object.
+ * Used as a safety net before persistence to ensure computed fields
+ * are never written to storage.
+ *
+ * @template T - The original entity type (stored fields only)
+ * @template C - The computed fields config type
+ *
+ * @param entity - The entity (possibly with computed fields attached)
+ * @param config - The computed fields configuration that defines which keys to strip
+ * @returns A new object with only stored fields (computed fields removed)
+ *
+ * @example
+ * ```ts
+ * const entityWithComputed = {
+ *   id: "1",
+ *   title: "Dune",
+ *   year: 1965,
+ *   displayName: "Dune (1965)",  // computed
+ *   isClassic: true,              // computed
+ * }
+ * const config = {
+ *   displayName: (b) => `${b.title} (${b.year})`,
+ *   isClassic: (b) => b.year < 1980,
+ * }
+ * const stored = stripComputedFields(entityWithComputed, config)
+ * // { id: "1", title: "Dune", year: 1965 }
+ * ```
+ */
+export const stripComputedFields = (entity, config) => {
+    // When config is empty or undefined, return entity unchanged
+    if (config === undefined || Object.keys(config).length === 0) {
+        return entity;
+    }
+    const computedKeys = new Set(Object.keys(config));
+    const result = {};
+    for (const key of Object.keys(entity)) {
+        if (!computedKeys.has(key)) {
+            result[key] = entity[key];
+        }
+    }
+    return result;
+};
+/**
+ * Check if any computed fields are selected based on the select configuration.
+ *
+ * @param computedConfig - The computed fields configuration
+ * @param select - The select configuration (object with true values for selected fields)
+ * @returns true if any computed field is selected (or select is undefined meaning all fields)
+ *
+ * @example
+ * ```ts
+ * const computedConfig = {
+ *   displayName: (b) => `${b.title} (${b.year})`,
+ *   isClassic: (b) => b.year < 1980,
+ * }
+ *
+ * // No select = all fields including computed
+ * hasSelectedComputedFields(computedConfig, undefined) // true
+ *
+ * // Select includes computed field
+ * hasSelectedComputedFields(computedConfig, { title: true, displayName: true }) // true
+ *
+ * // Select excludes all computed fields
+ * hasSelectedComputedFields(computedConfig, { title: true, year: true }) // false
+ * ```
+ */
+export const hasSelectedComputedFields = (computedConfig, select) => {
+    // No computed config means no computed fields to select
+    if (computedConfig === undefined ||
+        Object.keys(computedConfig).length === 0) {
+        return false;
+    }
+    // No select means all fields are selected (including computed)
+    if (select === undefined) {
+        return true;
+    }
+    // Check if any computed field key is in the select config
+    const computedKeys = Object.keys(computedConfig);
+    const selectKeys = Object.keys(select);
+    for (const computedKey of computedKeys) {
+        if (selectKeys.includes(computedKey) && select[computedKey] === true) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * Apply computed field resolution with lazy skip optimization.
+ *
+ * When `select` is provided and has no intersection with computed field keys,
+ * bypasses resolution entirely by returning the stream unchanged. This avoids
+ * unnecessary computation when only stored fields are needed.
+ *
+ * @template T - The entity type (stored fields, possibly with populated relationships)
+ * @template C - The computed fields config type
+ *
+ * @param config - The computed fields configuration (field name → derivation function), or undefined
+ * @param select - The select configuration (object with true values for selected fields), or undefined
+ * @returns A stream combinator function
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   displayName: (b) => `${b.title} (${b.year})`,
+ *   isClassic: (b) => b.year < 1980,
+ * }
+ *
+ * // When select includes computed fields, resolution is applied
+ * const enrichedStream = stream.pipe(
+ *   resolveComputedStreamWithLazySkip(config, { title: true, displayName: true })
+ * )
+ *
+ * // When select excludes all computed fields, resolution is skipped
+ * const storedOnlyStream = stream.pipe(
+ *   resolveComputedStreamWithLazySkip(config, { title: true, year: true })
+ * )
+ * // → stream returned unchanged, no resolution overhead
+ * ```
+ */
+export const resolveComputedStreamWithLazySkip = (config, select) => (stream) => {
+    // Check if any computed fields are selected
+    // Cast to unknown first to bypass contravariance check - we're only checking keys
+    if (!hasSelectedComputedFields(config, select)) {
+        // No computed fields selected, return stream unchanged
+        return stream;
+    }
+    // Computed fields are selected, apply resolution
+    return Stream.map(stream, (entity) => resolveComputedFields(entity, config));
+};
+//# sourceMappingURL=resolve-computed.js.map

package/dist/operations/query/resolve-computed.js.map

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

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

@@ -0,0 +1,110 @@
+/**
+ * Full-text search operations: tokenization, matching, and relevance scoring.
+ *
+ * Provides pure functions for text search functionality including
+ * tokenization, stop word filtering, and relevance-based ranking.
+ */
+/**
+ * Tokenize text into normalized tokens.
+ *
+ * Splits on whitespace, strips leading/trailing punctuation characters,
+ * lowercases all tokens, and filters out empty strings.
+ *
+ * @param text - The text to tokenize
+ * @returns Array of normalized tokens
+ *
+ * @example
+ * ```ts
+ * tokenize("Gibson, William")
+ * // => ["gibson", "william"]
+ *
+ * tokenize("The Left Hand of Darkness")
+ * // => ["the", "left", "hand", "of", "darkness"]
+ *
+ * tokenize("  ")
+ * // => []
+ *
+ * tokenize("")
+ * // => []
+ * ```
+ */
+export declare function tokenize(text: string): ReadonlyArray<string>;
+/**
+ * Tokenize text with optional stop word filtering.
+ *
+ * Calls `tokenize` then optionally filters out common stop words
+ * (articles, prepositions, conjunctions, etc.) that typically don't
+ * contribute to search relevance.
+ *
+ * @param text - The text to tokenize
+ * @param removeStopWords - Whether to filter out stop words
+ * @returns Array of normalized tokens, optionally without stop words
+ *
+ * @example
+ * ```ts
+ * tokenizeWithStopWords("The Left Hand of Darkness", false)
+ * // => ["the", "left", "hand", "of", "darkness"]
+ *
+ * tokenizeWithStopWords("The Left Hand of Darkness", true)
+ * // => ["left", "hand", "darkness"]
+ * ```
+ */
+export declare function tokenizeWithStopWords(text: string, removeStopWords: boolean): ReadonlyArray<string>;
+/**
+ * Compute the relevance score for a single field value against query tokens.
+ *
+ * Scoring uses three factors combined multiplicatively:
+ * 1. **Term coverage**: Fraction of query tokens that matched (0..1)
+ * 2. **Term frequency (TF)**: How many times query tokens appear in the field
+ * 3. **Field length normalization**: Shorter fields score higher for same match
+ *
+ * Prefix matches (via startsWith) count toward matching but score slightly lower
+ * than exact matches to preserve ranking quality.
+ *
+ * @param fieldValue - The field value to score
+ * @param queryTokens - The tokenized search query
+ * @returns Relevance score (0 if no tokens match)
+ *
+ * @example
+ * ```ts
+ * computeFieldScore("Dune", ["dune"])
+ * // => ~1.44 (exact match, short field)
+ *
+ * computeFieldScore("The Left Hand of Darkness", ["left", "hand"])
+ * // => ~0.29 (2/2 coverage, longer field)
+ *
+ * computeFieldScore("Neuromancer", ["neuro"])
+ * // => ~0.72 (prefix match, reduced score)
+ *
+ * computeFieldScore("Dune", ["xyz"])
+ * // => 0 (no match)
+ * ```
+ */
+export declare function computeFieldScore(fieldValue: string, queryTokens: ReadonlyArray<string>): number;
+/**
+ * Compute the total relevance score for an entity across multiple fields.
+ *
+ * Sums the field scores for all specified fields. Fields that are not
+ * present on the entity or are not strings are skipped (score 0).
+ *
+ * @param entity - The entity to score
+ * @param queryTokens - The tokenized search query
+ * @param fields - The fields to search across
+ * @returns Total relevance score (0 if no fields match)
+ *
+ * @example
+ * ```ts
+ * const book = { title: "Dune", author: "Frank Herbert", year: 1965 }
+ *
+ * computeSearchScore(book, ["dune"], ["title", "author"])
+ * // => ~1.44 (matches in title only)
+ *
+ * computeSearchScore(book, ["herbert", "dune"], ["title", "author"])
+ * // => ~2.88 (matches in both fields)
+ *
+ * computeSearchScore(book, ["xyz"], ["title", "author"])
+ * // => 0 (no matches)
+ * ```
+ */
+export declare function computeSearchScore(entity: Record<string, unknown>, queryTokens: ReadonlyArray<string>, fields: ReadonlyArray<string>): number;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/operations/query/search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,OAAO,GACtB,aAAa,CAAC,MAAM,CAAC,CAMvB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAChC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,GAChC,MAAM,CAqDR;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,EAClC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAC3B,MAAM,CAoBR"}

package/dist/operations/query/search.js

@@ -0,0 +1,188 @@
+/**
+ * Full-text search operations: tokenization, matching, and relevance scoring.
+ *
+ * Provides pure functions for text search functionality including
+ * tokenization, stop word filtering, and relevance-based ranking.
+ */
+import { STOP_WORDS } from "../../types/search-types.js";
+// ============================================================================
+// Tokenization
+// ============================================================================
+/**
+ * Tokenize text into normalized tokens.
+ *
+ * Splits on whitespace, strips leading/trailing punctuation characters,
+ * lowercases all tokens, and filters out empty strings.
+ *
+ * @param text - The text to tokenize
+ * @returns Array of normalized tokens
+ *
+ * @example
+ * ```ts
+ * tokenize("Gibson, William")
+ * // => ["gibson", "william"]
+ *
+ * tokenize("The Left Hand of Darkness")
+ * // => ["the", "left", "hand", "of", "darkness"]
+ *
+ * tokenize("  ")
+ * // => []
+ *
+ * tokenize("")
+ * // => []
+ * ```
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/\s+/)
+        .map((t) => t.replace(/^[^\w]+|[^\w]+$/g, ""))
+        .filter((t) => t.length > 0);
+}
+/**
+ * Tokenize text with optional stop word filtering.
+ *
+ * Calls `tokenize` then optionally filters out common stop words
+ * (articles, prepositions, conjunctions, etc.) that typically don't
+ * contribute to search relevance.
+ *
+ * @param text - The text to tokenize
+ * @param removeStopWords - Whether to filter out stop words
+ * @returns Array of normalized tokens, optionally without stop words
+ *
+ * @example
+ * ```ts
+ * tokenizeWithStopWords("The Left Hand of Darkness", false)
+ * // => ["the", "left", "hand", "of", "darkness"]
+ *
+ * tokenizeWithStopWords("The Left Hand of Darkness", true)
+ * // => ["left", "hand", "darkness"]
+ * ```
+ */
+export function tokenizeWithStopWords(text, removeStopWords) {
+    const tokens = tokenize(text);
+    if (!removeStopWords) {
+        return tokens;
+    }
+    return tokens.filter((token) => !STOP_WORDS.has(token));
+}
+// ============================================================================
+// Relevance Scoring
+// ============================================================================
+/**
+ * Compute the relevance score for a single field value against query tokens.
+ *
+ * Scoring uses three factors combined multiplicatively:
+ * 1. **Term coverage**: Fraction of query tokens that matched (0..1)
+ * 2. **Term frequency (TF)**: How many times query tokens appear in the field
+ * 3. **Field length normalization**: Shorter fields score higher for same match
+ *
+ * Prefix matches (via startsWith) count toward matching but score slightly lower
+ * than exact matches to preserve ranking quality.
+ *
+ * @param fieldValue - The field value to score
+ * @param queryTokens - The tokenized search query
+ * @returns Relevance score (0 if no tokens match)
+ *
+ * @example
+ * ```ts
+ * computeFieldScore("Dune", ["dune"])
+ * // => ~1.44 (exact match, short field)
+ *
+ * computeFieldScore("The Left Hand of Darkness", ["left", "hand"])
+ * // => ~0.29 (2/2 coverage, longer field)
+ *
+ * computeFieldScore("Neuromancer", ["neuro"])
+ * // => ~0.72 (prefix match, reduced score)
+ *
+ * computeFieldScore("Dune", ["xyz"])
+ * // => 0 (no match)
+ * ```
+ */
+export function computeFieldScore(fieldValue, queryTokens) {
+    // Handle edge cases
+    if (queryTokens.length === 0) {
+        return 0;
+    }
+    const fieldTokens = tokenize(fieldValue);
+    if (fieldTokens.length === 0) {
+        return 0;
+    }
+    // Count matched tokens and compute term frequency
+    let matchedTermCount = 0;
+    let termFrequencySum = 0;
+    for (const queryToken of queryTokens) {
+        let tokenMatched = false;
+        let tokenFrequency = 0;
+        for (const fieldToken of fieldTokens) {
+            if (fieldToken === queryToken) {
+                // Exact match: full weight
+                tokenFrequency += 1;
+                tokenMatched = true;
+            }
+            else if (fieldToken.startsWith(queryToken)) {
+                // Prefix match: reduced weight (0.5x)
+                tokenFrequency += 0.5;
+                tokenMatched = true;
+            }
+        }
+        if (tokenMatched) {
+            matchedTermCount += 1;
+            termFrequencySum += tokenFrequency;
+        }
+    }
+    // No matches means score of 0
+    if (matchedTermCount === 0) {
+        return 0;
+    }
+    // Compute score using the three factors:
+    // 1. Coverage: fraction of query tokens that matched
+    const coverage = matchedTermCount / queryTokens.length;
+    // 2. TF boost: more occurrences = higher score
+    const tfBoost = 1 + termFrequencySum / fieldTokens.length;
+    // 3. Length normalization: shorter fields score higher
+    const lengthNorm = 1 / Math.log(1 + fieldTokens.length);
+    return coverage * tfBoost * lengthNorm;
+}
+/**
+ * Compute the total relevance score for an entity across multiple fields.
+ *
+ * Sums the field scores for all specified fields. Fields that are not
+ * present on the entity or are not strings are skipped (score 0).
+ *
+ * @param entity - The entity to score
+ * @param queryTokens - The tokenized search query
+ * @param fields - The fields to search across
+ * @returns Total relevance score (0 if no fields match)
+ *
+ * @example
+ * ```ts
+ * const book = { title: "Dune", author: "Frank Herbert", year: 1965 }
+ *
+ * computeSearchScore(book, ["dune"], ["title", "author"])
+ * // => ~1.44 (matches in title only)
+ *
+ * computeSearchScore(book, ["herbert", "dune"], ["title", "author"])
+ * // => ~2.88 (matches in both fields)
+ *
+ * computeSearchScore(book, ["xyz"], ["title", "author"])
+ * // => 0 (no matches)
+ * ```
+ */
+export function computeSearchScore(entity, queryTokens, fields) {
+    // Handle edge cases
+    if (queryTokens.length === 0 || fields.length === 0) {
+        return 0;
+    }
+    let totalScore = 0;
+    for (const field of fields) {
+        const fieldValue = entity[field];
+        // Skip non-string fields
+        if (typeof fieldValue !== "string") {
+            continue;
+        }
+        totalScore += computeFieldScore(fieldValue, queryTokens);
+    }
+    return totalScore;
+}
+//# sourceMappingURL=search.js.map

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

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

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

@@ -0,0 +1,27 @@
+import { Stream } from "effect";
+/**
+ * A select configuration can be either:
+ * - Object-based: `{ name: true, email: true, company: { name: true } }`
+ * - Array-based: `["name", "email"]` (picks those fields)
+ */
+type SelectConfig = Record<string, unknown> | ReadonlyArray<string>;
+/**
+ * Apply a field selection as a Stream combinator.
+ * Returns a function that transforms Stream<T> → Stream<T>, projecting each entity
+ * to only the selected fields.
+ *
+ * Supports both object-based (`{ name: true, email: true }`) and
+ * array-based (`["name", "email"]`) selection configs.
+ * Nested selection on populated relationships is supported via object-based config:
+ * `{ name: true, company: { name: true } }`.
+ */
+export declare const applySelect: <T extends Record<string, unknown>>(select: SelectConfig | undefined) => <E, R>(stream: Stream.Stream<T, E, R>) => Stream.Stream<T, E, R>;
+/**
+ * Apply a field selection to an array of items.
+ *
+ * This is used by cursor pagination where items are collected before selection.
+ * Supports both object-based and array-based selection configs.
+ */
+export declare const applySelectToArray: <T extends Record<string, unknown>>(items: ReadonlyArray<T>, select: SelectConfig | undefined) => ReadonlyArray<T>;
+export {};
+//# sourceMappingURL=select-stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-stream.d.ts","sourceRoot":"","sources":["../../../src/operations/query/select-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;GAIG;AACH,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAsDpE;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACtB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,YAAY,GAAG,SAAS,MACnE,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,CAmB5D,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,QAAQ,YAAY,GAAG,SAAS,KAC9B,aAAa,CAAC,CAAC,CAcjB,CAAC"}

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

@@ -0,0 +1,88 @@
+import { Stream } from "effect";
+/**
+ * Type guard to check if a value is a record (non-null, non-array object).
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Apply object-based field selection to a single item.
+ * Handles nested selection for populated relationships (both objects and arrays).
+ */
+function applyObjectSelect(item, selection) {
+    const result = {};
+    for (const [key, value] of Object.entries(selection)) {
+        if (!(key in item))
+            continue;
+        if (value === true) {
+            result[key] = item[key];
+        }
+        else if (isRecord(value)) {
+            // Nested selection for populated relationships
+            const nestedData = item[key];
+            if (Array.isArray(nestedData)) {
+                result[key] = nestedData
+                    .filter(isRecord)
+                    .map((nested) => applyObjectSelect(nested, value));
+            }
+            else if (isRecord(nestedData)) {
+                result[key] = applyObjectSelect(nestedData, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Convert an array-based select config to an object-based one.
+ * `["name", "email"]` becomes `{ name: true, email: true }`.
+ */
+function arraySelectToObject(fields) {
+    const result = {};
+    for (const field of fields) {
+        result[field] = true;
+    }
+    return result;
+}
+/**
+ * Apply a field selection as a Stream combinator.
+ * Returns a function that transforms Stream<T> → Stream<T>, projecting each entity
+ * to only the selected fields.
+ *
+ * Supports both object-based (`{ name: true, email: true }`) and
+ * array-based (`["name", "email"]`) selection configs.
+ * Nested selection on populated relationships is supported via object-based config:
+ * `{ name: true, company: { name: true } }`.
+ */
+export const applySelect = (select) => (stream) => {
+    if (select === undefined || select === null)
+        return stream;
+    if (Array.isArray(select)) {
+        if (select.length === 0)
+            return stream;
+        const objectSelect = arraySelectToObject(select);
+        return Stream.map(stream, (item) => applyObjectSelect(item, objectSelect));
+    }
+    if (isRecord(select) && Object.keys(select).length === 0)
+        return stream;
+    return Stream.map(stream, (item) => applyObjectSelect(item, select));
+};
+/**
+ * Apply a field selection to an array of items.
+ *
+ * This is used by cursor pagination where items are collected before selection.
+ * Supports both object-based and array-based selection configs.
+ */
+export const applySelectToArray = (items, select) => {
+    if (select === undefined || select === null)
+        return items;
+    if (Array.isArray(select)) {
+        if (select.length === 0)
+            return items;
+        const objectSelect = arraySelectToObject(select);
+        return items.map((item) => applyObjectSelect(item, objectSelect));
+    }
+    if (isRecord(select) && Object.keys(select).length === 0)
+        return items;
+    return items.map((item) => applyObjectSelect(item, select));
+};
+//# sourceMappingURL=select-stream.js.map

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

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