@proseql/core 0.1.0

package/dist/operations/relationships/populate-stream.js

@@ -0,0 +1,159 @@
+import { Effect, Ref, Stream } from "effect";
+import { DanglingReferenceError } from "../../errors/query-errors.js";
+/**
+ * Maximum recursion depth for nested population (mirrors PopulateConfig type depth limit).
+ */
+const MAX_POPULATE_DEPTH = 5;
+/**
+ * Type guard: is value a non-null, non-array object?
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Type guard for populate config objects.
+ */
+function isPopulateConfig(value) {
+    return isRecord(value);
+}
+/**
+ * Derive the foreign key field for an inverse relationship.
+ *
+ * Priority:
+ * 1. Explicit `foreignKey` on the inverse relationship definition
+ * 2. Explicit `foreignKey` on the corresponding ref relationship in the target collection
+ * 3. Default naming convention: singularize source collection name + "Id"
+ */
+function resolveInverseForeignKey(relationship, collectionName, dbConfig) {
+    if (relationship.foreignKey) {
+        return relationship.foreignKey;
+    }
+    const targetConfig = dbConfig[relationship.target];
+    if (targetConfig) {
+        const reverseRel = Object.entries(targetConfig.relationships).find(([, rel]) => rel.type === "ref" && rel.target === collectionName);
+        if (reverseRel?.[1].foreignKey) {
+            return reverseRel[1].foreignKey;
+        }
+    }
+    // Default: singularize collection name + "Id"
+    const singularName = collectionName.endsWith("ies")
+        ? `${collectionName.slice(0, -3)}y`
+        : collectionName.replace(/s$/, "");
+    return `${singularName}Id`;
+}
+/**
+ * Populate a single item's relationships recursively.
+ *
+ * For each relationship key in the populate config:
+ * - `ref`: look up a single entity in the target collection by foreign key
+ * - `inverse`: find all entities whose foreign key points back to this item
+ *
+ * When the populate value is a nested config object (not just `true`),
+ * recursively populate the related entity's relationships using the
+ * target collection's relationship definitions.
+ *
+ * Recursion stops at MAX_POPULATE_DEPTH (5) to prevent infinite loops
+ * in circular relationship graphs.
+ */
+function populateItem(item, populateConfig, stateRefs, dbConfig, collectionName, depth) {
+    return Effect.gen(function* () {
+        const sourceConfig = dbConfig[collectionName];
+        if (!sourceConfig)
+            return item;
+        const relationships = sourceConfig.relationships;
+        const populateEntries = Object.entries(populateConfig).filter(([key]) => relationships[key] !== undefined);
+        if (populateEntries.length === 0)
+            return item;
+        const populated = { ...item };
+        for (const [key, value] of populateEntries) {
+            const relationship = relationships[key];
+            const targetRef = stateRefs[relationship.target];
+            if (!targetRef)
+                continue;
+            const targetMap = yield* Ref.get(targetRef);
+            if (relationship.type === "ref") {
+                const foreignKeyField = relationship.foreignKey || `${key}Id`;
+                const foreignKeyValue = item[foreignKeyField];
+                if (typeof foreignKeyValue === "string") {
+                    const related = targetMap.get(foreignKeyValue);
+                    if (related) {
+                        populated[key] = yield* maybeRecurse(related, value, relationship.target, stateRefs, dbConfig, depth);
+                    }
+                    else {
+                        yield* new DanglingReferenceError({
+                            collection: relationship.target,
+                            field: foreignKeyField,
+                            targetId: foreignKeyValue,
+                            message: `Entity in "${collectionName}" references missing "${relationship.target}" with ${foreignKeyField}="${foreignKeyValue}"`,
+                        });
+                    }
+                }
+                else {
+                    populated[key] = undefined;
+                }
+            }
+            else if (relationship.type === "inverse") {
+                const foreignKeyField = resolveInverseForeignKey(relationship, collectionName, dbConfig);
+                const relatedItems = [];
+                for (const entity of targetMap.values()) {
+                    if (entity[foreignKeyField] === item.id) {
+                        relatedItems.push(entity);
+                    }
+                }
+                if (value === true || !isRecord(value)) {
+                    populated[key] = relatedItems;
+                }
+                else {
+                    const populatedRelated = [];
+                    for (const relItem of relatedItems) {
+                        populatedRelated.push(yield* maybeRecurse(relItem, value, relationship.target, stateRefs, dbConfig, depth));
+                    }
+                    populated[key] = populatedRelated;
+                }
+            }
+        }
+        return populated;
+    });
+}
+/**
+ * If the populate value is a nested config and we haven't hit the depth limit,
+ * recursively populate the related entity. Otherwise return the entity as-is.
+ */
+function maybeRecurse(entity, value, targetCollectionName, stateRefs, dbConfig, depth) {
+    if (value === true ||
+        !isPopulateConfig(value) ||
+        depth >= MAX_POPULATE_DEPTH) {
+        return Effect.succeed(entity);
+    }
+    return populateItem(entity, value, stateRefs, dbConfig, targetCollectionName, depth + 1);
+}
+/**
+ * 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 const applyPopulate = (populateConfig, stateRefs, dbConfig, collectionName) => (stream) => {
+    if (!populateConfig || !isPopulateConfig(populateConfig))
+        return stream;
+    const sourceConfig = dbConfig[collectionName];
+    if (!sourceConfig)
+        return stream;
+    const relationships = sourceConfig.relationships;
+    const populateEntries = Object.entries(populateConfig).filter(([key]) => relationships[key] !== undefined);
+    if (populateEntries.length === 0)
+        return stream;
+    return Stream.mapEffect(stream, (item) => populateItem(item, populateConfig, stateRefs, dbConfig, collectionName, 0));
+};
+//# sourceMappingURL=populate-stream.js.map

package/dist/operations/relationships/populate-stream.js.map

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

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

@@ -0,0 +1,15 @@
+type RelationshipType = "ref" | "inverse";
+interface Relationship {
+    type: RelationshipType;
+    target: string;
+    foreignKey?: string;
+}
+interface CollectionConfig {
+    relationships: Record<string, Relationship>;
+}
+export type PopulateValue = boolean | Record<string, unknown>;
+export declare function isPopulateConfig(value: unknown): value is Record<string, PopulateValue>;
+export declare function applyPopulate<T extends Record<string, unknown>>(item: T, populateConfig: Record<string, PopulateValue>, allData: Record<string, unknown[]>, relationships: Record<string, Relationship>, collectionName: string, config: Record<string, CollectionConfig>): T;
+export declare function populateRelationships<T extends Record<string, unknown>>(items: T[], populateConfig: Record<string, PopulateValue> | undefined, allData: Record<string, unknown[]>, relationships: Record<string, Relationship>, collectionName: string, config: Record<string, CollectionConfig>): T[];
+export {};
+//# sourceMappingURL=populate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"populate.d.ts","sourceRoot":"","sources":["../../../src/operations/relationships/populate.ts"],"names":[],"mappings":"AAIA,KAAK,gBAAgB,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1C,UAAU,YAAY;IACrB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,gBAAgB;IACzB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAG9D,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAExC;AAwFD,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,IAAI,EAAE,CAAC,EACP,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC7C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC3C,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACtC,CAAC,CA2MH;AAGD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,KAAK,EAAE,CAAC,EAAE,EACV,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,EACzD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC3C,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACtC,CAAC,EAAE,CAaL"}

package/dist/operations/relationships/populate.js

@@ -0,0 +1,228 @@
+import { isValidWhereClause } from "../query/filter.js";
+import { applyObjectSelection } from "../query/select.js";
+// Type guard for populate config objects
+export function isPopulateConfig(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// Type guard to check if value is a record
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Type guard for string arrays
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function isSelectionConfig(value) {
+    return isStringArray(value) || isRecord(value);
+}
+// Safe extraction of nested populate configuration
+function extractNestedConfig(value) {
+    const { select, populate, ...otherProps } = value;
+    const validNestedPopulate = {};
+    // Safely copy otherProps that are valid PopulateValue types
+    for (const [key, value] of Object.entries(otherProps)) {
+        if (typeof value === "boolean" || isRecord(value)) {
+            validNestedPopulate[key] = value;
+        }
+    }
+    // Safely merge populate if it's valid
+    if (isPopulateConfig(populate)) {
+        for (const [key, value] of Object.entries(populate)) {
+            if (typeof value === "boolean" || isRecord(value)) {
+                validNestedPopulate[key] = value;
+            }
+        }
+    }
+    const result = {
+        nestedPopulate: validNestedPopulate,
+    };
+    if (isSelectionConfig(select)) {
+        result.select = select;
+    }
+    return result;
+}
+// Helper function to find a single related item
+function findRelatedItem(item, foreignKeyField, targetData) {
+    if (!targetData || !isValidWhereClause(item))
+        return undefined;
+    return targetData.find((target) => {
+        if (!isValidWhereClause(target))
+            return false;
+        return target.id === item[foreignKeyField];
+    });
+}
+// Helper function to find multiple related items
+function findRelatedItems(item, foreignKeyField, targetData) {
+    if (!targetData || !isValidWhereClause(item))
+        return [];
+    return targetData.filter((target) => {
+        if (!isValidWhereClause(target))
+            return false;
+        return target[foreignKeyField] === item.id;
+    });
+}
+// Helper function to apply populate configuration recursively
+export function applyPopulate(item, populateConfig, allData, relationships, collectionName, config) {
+    const populated = { ...item };
+    for (const [key, value] of Object.entries(populateConfig)) {
+        const relationship = relationships[key];
+        if (!relationship)
+            continue;
+        const targetData = allData[relationship.target];
+        if (relationship.type === "ref") {
+            // Handle ref relationships
+            const foreignKeyField = relationship.foreignKey || `${key}Id`;
+            const relatedItem = findRelatedItem(populated, foreignKeyField, targetData);
+            if (relatedItem && value === true) {
+                Object.assign(populated, { [key]: relatedItem });
+            }
+            else if (relatedItem && isPopulateConfig(value)) {
+                // Recursively populate nested config
+                const targetConfig = config[relationship.target];
+                if (targetConfig) {
+                    // Extract nested populate config and select from value safely
+                    const { select, nestedPopulate } = extractNestedConfig(value);
+                    // Apply nested population first
+                    let populatedRelated = relatedItem;
+                    if (Object.keys(nestedPopulate).length > 0) {
+                        populatedRelated = applyPopulate(relatedItem, nestedPopulate, allData, targetConfig.relationships, relationship.target, config);
+                    }
+                    // Apply field selection if specified (supports both array and object-based)
+                    if (select) {
+                        let selectedFields;
+                        if (isStringArray(select)) {
+                            // Convert array to object format
+                            const objectSelect = {};
+                            for (const field of select) {
+                                objectSelect[field] = true;
+                            }
+                            selectedFields = applyObjectSelection(populatedRelated, objectSelect);
+                        }
+                        else if (isRecord(select)) {
+                            selectedFields = applyObjectSelection(populatedRelated, select);
+                        }
+                        else {
+                            // Invalid select format, skip selection
+                            selectedFields = populatedRelated;
+                        }
+                        // For object-based selection, the nested fields are already handled by applyObjectSelection
+                        // For array-based selection, preserve any populated fields that are defined in relationships
+                        let finalResult = selectedFields;
+                        if (isStringArray(select)) {
+                            // Only for array-based selection, we need to preserve populated relationships
+                            finalResult = { ...selectedFields };
+                            // Check relationships in the target config to know which fields are populated
+                            for (const [relKey, _relDef] of Object.entries(targetConfig.relationships)) {
+                                if (nestedPopulate[relKey] && relKey in populatedRelated) {
+                                    finalResult[relKey] = populatedRelated[relKey];
+                                }
+                            }
+                        }
+                        populatedRelated = finalResult;
+                    }
+                    Object.assign(populated, { [key]: populatedRelated });
+                }
+            }
+            else {
+                Object.assign(populated, { [key]: undefined });
+            }
+        }
+        else if (relationship.type === "inverse") {
+            // Handle inverse relationships
+            // For inverse relationships, we need to find items in the target collection
+            // that have a foreign key pointing back to this collection
+            // First, check if there's a specific foreignKey configured
+            let foreignKeyField;
+            if (relationship.foreignKey) {
+                foreignKeyField = relationship.foreignKey;
+            }
+            else {
+                // Look for the corresponding ref relationship in the target collection
+                const targetConfig = config[relationship.target];
+                if (targetConfig) {
+                    // Find the relationship that points back to our collection
+                    const reverseRelationship = Object.entries(targetConfig.relationships).find(([, rel]) => rel.type === "ref" && rel.target === collectionName);
+                    if (reverseRelationship?.[1].foreignKey) {
+                        foreignKeyField = reverseRelationship[1].foreignKey;
+                    }
+                    else {
+                        // Fall back to the default naming convention
+                        const singularName = collectionName.endsWith("ies")
+                            ? `${collectionName.slice(0, -3)}y` // companies -> company, industries -> industry
+                            : collectionName.replace(/s$/, ""); // users -> user, posts -> post
+                        foreignKeyField = `${singularName}Id`;
+                    }
+                }
+                else {
+                    // Fall back to the default naming convention
+                    const singularName = collectionName.endsWith("ies")
+                        ? `${collectionName.slice(0, -3)}y` // companies -> company, industries -> industry
+                        : collectionName.replace(/s$/, ""); // users -> user, posts -> post
+                    foreignKeyField = `${singularName}Id`;
+                }
+            }
+            const relatedItems = findRelatedItems(populated, foreignKeyField, targetData);
+            if (value === true) {
+                Object.assign(populated, { [key]: relatedItems });
+            }
+            else if (isPopulateConfig(value)) {
+                // Recursively populate each item in the array
+                const targetConfig = config[relationship.target];
+                if (targetConfig) {
+                    // Extract nested populate config and select from value safely
+                    const { select, nestedPopulate } = extractNestedConfig(value);
+                    const populatedItems = relatedItems.map((relItem) => {
+                        // Apply nested population first
+                        let populatedItem = relItem;
+                        if (Object.keys(nestedPopulate).length > 0) {
+                            populatedItem = applyPopulate(relItem, nestedPopulate, allData, targetConfig.relationships, relationship.target, config);
+                        }
+                        // Apply field selection if specified (supports both array and object-based)
+                        if (select) {
+                            let selectedFields;
+                            if (isStringArray(select)) {
+                                // Convert array to object format
+                                const objectSelect = {};
+                                for (const field of select) {
+                                    objectSelect[field] = true;
+                                }
+                                selectedFields = applyObjectSelection(populatedItem, objectSelect);
+                            }
+                            else if (isRecord(select)) {
+                                selectedFields = applyObjectSelection(populatedItem, select);
+                            }
+                            else {
+                                // Invalid select format, skip selection
+                                selectedFields = populatedItem;
+                            }
+                            // For object-based selection, the nested fields are already handled by applyObjectSelection
+                            // For array-based selection, preserve any populated fields that are defined in relationships
+                            let finalResult = selectedFields;
+                            if (isStringArray(select)) {
+                                // Only for array-based selection, we need to preserve populated relationships
+                                finalResult = { ...selectedFields };
+                                // Check relationships in the target config to know which fields are populated
+                                for (const [relKey, _relDef] of Object.entries(targetConfig.relationships)) {
+                                    if (nestedPopulate[relKey] && relKey in populatedItem) {
+                                        finalResult[relKey] = populatedItem[relKey];
+                                    }
+                                }
+                            }
+                            populatedItem = finalResult;
+                        }
+                        return populatedItem;
+                    });
+                    Object.assign(populated, { [key]: populatedItems });
+                }
+            }
+        }
+    }
+    return populated;
+}
+// Helper function to populate relationships
+export function populateRelationships(items, populateConfig, allData, relationships, collectionName, config) {
+    if (!populateConfig || !isPopulateConfig(populateConfig))
+        return items;
+    return items.map((item) => applyPopulate(item, populateConfig, allData, relationships, collectionName, config));
+}
+//# sourceMappingURL=populate.js.map

package/dist/operations/relationships/populate.js.map

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

package/dist/plugins/plugin-hooks.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Plugin hooks utilities for merging global hooks with collection hooks.
+ *
+ * Global plugin hooks run before collection-specific hooks because they represent
+ * cross-cutting concerns (audit logging, encryption) that should see data before
+ * collection-specific transformations.
+ */
+import type { HooksConfig } from "../types/hook-types.js";
+import type { GlobalHooksConfig } from "./plugin-types.js";
+/**
+ * Merges global plugin hooks with collection-specific hooks.
+ *
+ * For each hook type, global hooks are prepended before collection hooks.
+ * This ensures global hooks (cross-cutting concerns) run first.
+ *
+ * Type narrowing: Global hooks are `HooksConfig<Record<string, unknown>>`,
+ * collection hooks are `HooksConfig<T>`. The merged result is `HooksConfig<T>`
+ * with global hooks cast appropriately.
+ *
+ * @param globalHooks - Global hooks from plugin registry (may be empty/undefined)
+ * @param collectionHooks - Collection-specific hooks (may be empty/undefined)
+ * @returns Merged hooks config with global hooks first
+ */
+export declare const mergeGlobalHooks: <T extends Record<string, unknown>>(globalHooks: GlobalHooksConfig | undefined, collectionHooks: HooksConfig<T> | undefined) => HooksConfig<T>;
+//# sourceMappingURL=plugin-hooks.d.ts.map

package/dist/plugins/plugin-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-hooks.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,aAAa,iBAAiB,GAAG,SAAS,EAC1C,iBAAiB,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,KACzC,WAAW,CAAC,CAAC,CA6Cf,CAAC"}

package/dist/plugins/plugin-hooks.js

@@ -0,0 +1,64 @@
+/**
+ * Plugin hooks utilities for merging global hooks with collection hooks.
+ *
+ * Global plugin hooks run before collection-specific hooks because they represent
+ * cross-cutting concerns (audit logging, encryption) that should see data before
+ * collection-specific transformations.
+ */
+/**
+ * Merges global plugin hooks with collection-specific hooks.
+ *
+ * For each hook type, global hooks are prepended before collection hooks.
+ * This ensures global hooks (cross-cutting concerns) run first.
+ *
+ * Type narrowing: Global hooks are `HooksConfig<Record<string, unknown>>`,
+ * collection hooks are `HooksConfig<T>`. The merged result is `HooksConfig<T>`
+ * with global hooks cast appropriately.
+ *
+ * @param globalHooks - Global hooks from plugin registry (may be empty/undefined)
+ * @param collectionHooks - Collection-specific hooks (may be empty/undefined)
+ * @returns Merged hooks config with global hooks first
+ */
+export const mergeGlobalHooks = (globalHooks, collectionHooks) => {
+    // If no global hooks, return collection hooks as-is (or empty object)
+    if (!globalHooks) {
+        return collectionHooks ?? {};
+    }
+    // If no collection hooks, cast global hooks to the collection type
+    if (!collectionHooks) {
+        return globalHooks;
+    }
+    // Merge each hook array: global first, then collection
+    // Note: Global hooks have Record<string, unknown> type and need casting
+    // to the specific collection type T. This is safe because global hooks
+    // operate on any entity shape and T extends Record<string, unknown>.
+    return {
+        beforeCreate: mergeHookArrays(globalHooks.beforeCreate, collectionHooks.beforeCreate),
+        afterCreate: mergeHookArrays(globalHooks.afterCreate, collectionHooks.afterCreate),
+        beforeUpdate: mergeHookArrays(globalHooks.beforeUpdate, collectionHooks.beforeUpdate),
+        afterUpdate: mergeHookArrays(globalHooks.afterUpdate, collectionHooks.afterUpdate),
+        beforeDelete: mergeHookArrays(globalHooks.beforeDelete, collectionHooks.beforeDelete),
+        afterDelete: mergeHookArrays(globalHooks.afterDelete, collectionHooks.afterDelete),
+        onChange: mergeHookArrays(globalHooks.onChange, collectionHooks.onChange),
+    };
+};
+/**
+ * Helper to merge two optional hook arrays.
+ * Global hooks come first, then collection hooks.
+ * Returns undefined if both are empty/undefined.
+ */
+const mergeHookArrays = (global, collection) => {
+    const hasGlobal = global && global.length > 0;
+    const hasCollection = collection && collection.length > 0;
+    if (!hasGlobal && !hasCollection) {
+        return undefined;
+    }
+    if (!hasGlobal) {
+        return collection;
+    }
+    if (!hasCollection) {
+        return global;
+    }
+    return [...global, ...collection];
+};
+//# sourceMappingURL=plugin-hooks.js.map

package/dist/plugins/plugin-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-hooks.js","sourceRoot":"","sources":["../../src/plugins/plugin-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC/B,WAA0C,EAC1C,eAA2C,EAC1B,EAAE;IACnB,sEAAsE;IACtE,IAAI,CAAC,WAAW,EAAE,CAAC;QAClB,OAAO,eAAe,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,mEAAmE;IACnE,IAAI,CAAC,eAAe,EAAE,CAAC;QACtB,OAAO,WAA6B,CAAC;IACtC,CAAC;IAED,uDAAuD;IACvD,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,OAAO;QACN,YAAY,EAAE,eAAe,CAC5B,WAAW,CAAC,YAA8C,EAC1D,eAAe,CAAC,YAAY,CAC5B;QACD,WAAW,EAAE,eAAe,CAC3B,WAAW,CAAC,WAA4C,EACxD,eAAe,CAAC,WAAW,CAC3B;QACD,YAAY,EAAE,eAAe,CAC5B,WAAW,CAAC,YAA8C,EAC1D,eAAe,CAAC,YAAY,CAC5B;QACD,WAAW,EAAE,eAAe,CAC3B,WAAW,CAAC,WAA4C,EACxD,eAAe,CAAC,WAAW,CAC3B;QACD,YAAY,EAAE,eAAe,CAC5B,WAAW,CAAC,YAA8C,EAC1D,eAAe,CAAC,YAAY,CAC5B;QACD,WAAW,EAAE,eAAe,CAC3B,WAAW,CAAC,WAA4C,EACxD,eAAe,CAAC,WAAW,CAC3B;QACD,QAAQ,EAAE,eAAe,CACxB,WAAW,CAAC,QAAsC,EAClD,eAAe,CAAC,QAAQ,CACxB;KACiB,CAAC;AACrB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,eAAe,GAAG,CACvB,MAAoC,EACpC,UAAwC,EACT,EAAE;IACjC,MAAM,SAAS,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9C,MAAM,aAAa,GAAG,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IAE1D,IAAI,CAAC,SAAS,IAAI,CAAC,aAAa,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO,UAAU,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IACf,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC;AACnC,CAAC,CAAC"}

package/dist/plugins/plugin-registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Plugin registry builder.
+ * Validates plugins and merges their contributions into a single registry.
+ */
+import { Effect } from "effect";
+import type { PluginError } from "../errors/plugin-errors.js";
+import type { PluginRegistry, ProseQLPlugin } from "./plugin-types.js";
+/**
+ * Builds a PluginRegistry from an array of plugins.
+ *
+ * This function:
+ * 1. Validates each plugin individually (structure, codecs, operators, generators)
+ * 2. Validates operator conflicts (between plugins and with built-in operators)
+ * 3. Validates dependencies (all declared dependencies must exist)
+ * 4. Merges codecs (append in registration order)
+ * 5. Merges operators into a Map (O(1) lookup)
+ * 6. Merges ID generators into a Map (O(1) lookup)
+ * 7. Merges global hooks (concatenate arrays in registration order)
+ *
+ * If plugins is undefined or empty, returns an empty registry.
+ *
+ * @param plugins - Array of plugins to validate and merge (optional)
+ * @returns Effect<PluginRegistry, PluginError> - The merged registry or validation error
+ */
+export declare const buildPluginRegistry: (plugins?: ReadonlyArray<ProseQLPlugin>) => Effect.Effect<PluginRegistry, PluginError>;
+//# sourceMappingURL=plugin-registry.d.ts.map

package/dist/plugins/plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAIX,cAAc,EACd,aAAa,EACb,MAAM,mBAAmB,CAAC;AA0B3B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,UAAU,aAAa,CAAC,aAAa,CAAC,KACpC,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,WAAW,CAmD3C,CAAC"}