@stoker-platform/utils 0.2.1

package/lib/src/operations/prepareDenormalized.js

@@ -0,0 +1,312 @@
+import { isRelationField } from "../schema/isRelationField.js";
+import { getDependencyIndexFields, getRoleExcludedFields } from "../schema/getIndexFields.js";
+import { isDependencyField } from "../schema/isDependencyField.js";
+import { getFieldNames } from "../schema/getFieldNames.js";
+import { getField } from "../schema/getField.js";
+import { isDeleteSentinel } from "./isDeleteSentinel.js";
+import { removeDeleteSentinels } from "./removeDeleteSentinels.js";
+import { getSingleFieldRelations } from "./getSingleFieldRelations.js";
+import { getLowercaseFields } from "./getLowercaseFields.js";
+import { getRecordSystemFields } from "../schema/getRecordSystemFields.js";
+export const prepareDenormalized = (operation, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+batch, path, docId, record, schema, collectionSchema, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+options, allRoleGroups, arrayUnion, arrayRemove, deleteField, dependencyRef, uniqueRef, privateRef, twoWayIncludeRef, twoWayDependencyRef, twoWayPrivateRef, originalRecord, noDelete, batchSize) => {
+    const { fields } = collectionSchema;
+    fields
+        .filter((field) => "unique" in field && field.unique)
+        .forEach((field) => {
+        if (operation !== "delete" &&
+            (typeof record[field.name] === "string" || typeof record[field.name] === "number")) {
+            batch.set(uniqueRef(field, record[field.name].toString().toLowerCase().replace(/\s/g, "---").replaceAll("/", "|||")), {
+                id: docId,
+                Collection_Path: path,
+            });
+            if (batchSize)
+                batchSize.size++;
+        }
+    });
+    fields.forEach((field) => {
+        if (isDependencyField(field, collectionSchema, schema)) {
+            const dependencyFieldsSchema = getDependencyIndexFields(field, collectionSchema, schema);
+            const dependencyFields = {};
+            if (record[field.name] !== undefined) {
+                dependencyFields[field.name] = record[field.name];
+                if (isRelationField(field)) {
+                    dependencyFields[`${field.name}_Array`] = record[`${field.name}_Array`];
+                }
+            }
+            dependencyFieldsSchema.forEach((dependencyField) => {
+                if (record[dependencyField.name] !== undefined) {
+                    if (isRelationField(dependencyField)) {
+                        dependencyFields[`${dependencyField.name}_Array`] = record[`${dependencyField.name}_Array`];
+                    }
+                    else {
+                        dependencyFields[dependencyField.name] = record[dependencyField.name];
+                    }
+                }
+            });
+            if (Object.keys(dependencyFields).length > 0) {
+                if (operation === "create") {
+                    dependencyFields.Collection_Path = path;
+                    dependencyFields.Collection_Path_String = path.join("/");
+                    batch.set(dependencyRef(field), dependencyFields);
+                }
+                if (operation === "update") {
+                    batch.update(dependencyRef(field), dependencyFields);
+                }
+                if (operation === "delete") {
+                    batch.delete(dependencyRef(field));
+                }
+                if (batchSize)
+                    batchSize.size++;
+            }
+        }
+    });
+    const roleGroups = allRoleGroups[collectionSchema.labels.collection];
+    for (const group of roleGroups) {
+        const excludedFields = getRoleExcludedFields(group, collectionSchema);
+        const recordToUpdate = { ...record };
+        excludedFields.forEach((field) => {
+            delete recordToUpdate[field.name];
+            delete recordToUpdate[`${field.name}_Array`];
+            delete recordToUpdate[`${field.name}_Single`];
+            delete recordToUpdate[`${field.name}_Lowercase`];
+        });
+        if (Object.keys(recordToUpdate).length > 0) {
+            if (operation === "create") {
+                recordToUpdate.Collection_Path ||= path;
+                recordToUpdate.Collection_Path_String = path.join("/");
+                batch.set(privateRef(group.key), recordToUpdate);
+            }
+            if (operation === "update") {
+                batch.update(privateRef(group.key), recordToUpdate);
+            }
+            if (operation === "delete") {
+                batch.delete(privateRef(group.key));
+            }
+            if (batchSize)
+                batchSize.size++;
+        }
+    }
+    const getDeleteFieldBatchSize = (targetSchema, targetField) => {
+        let batchSize = 1;
+        if (isDependencyField(targetField, targetSchema, schema)) {
+            batchSize++;
+        }
+        targetSchema.fields.forEach((targetSchemaField) => {
+            if (isDependencyField(targetSchemaField, targetSchema, schema)) {
+                const targetIndexFields = JSON.parse(getFieldNames(getDependencyIndexFields(targetSchemaField, targetSchema, schema)));
+                if (targetIndexFields.includes(targetField.name)) {
+                    batchSize++;
+                }
+            }
+        });
+        const targetRoleGroups = allRoleGroups[targetSchema.labels.collection];
+        for (const group of targetRoleGroups) {
+            if (group.fields.some((groupField) => groupField.name === targetField.name) &&
+                isRelationField(targetField)) {
+                batchSize++;
+            }
+        }
+        return batchSize;
+    };
+    const deleteFields = (field, targetSchema, targetField, id, relationPath) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const fieldUpdate = {};
+        fieldUpdate[`${targetField.name}.${docId}`] = deleteField();
+        fieldUpdate[`${targetField.name}_Array`] = arrayRemove(docId);
+        fieldUpdate[`${targetField.name}_Single`] = deleteField();
+        batch.update(twoWayIncludeRef(relationPath, id), fieldUpdate);
+        if (isDependencyField(targetField, targetSchema, schema)) {
+            batch.update(twoWayDependencyRef(field, targetField.name, id), {
+                [`${targetField.name}.${docId}`]: deleteField(),
+                [`${targetField.name}_Array`]: arrayRemove(docId),
+            });
+        }
+        targetSchema.fields.forEach((targetSchemaField) => {
+            if (isDependencyField(targetSchemaField, targetSchema, schema)) {
+                const targetIndexFields = JSON.parse(getFieldNames(getDependencyIndexFields(targetSchemaField, targetSchema, schema)));
+                if (targetIndexFields.includes(targetField.name)) {
+                    batch.update(twoWayDependencyRef(field, targetSchemaField.name, id), {
+                        [`${targetField.name}_Array`]: arrayRemove(docId),
+                    });
+                }
+            }
+        });
+        const targetRoleGroups = allRoleGroups[targetSchema.labels.collection];
+        for (const group of targetRoleGroups) {
+            if (group.fields.some((groupField) => groupField.name === targetField.name) &&
+                isRelationField(targetField)) {
+                batch.update(twoWayPrivateRef(field, group.key, id), fieldUpdate);
+            }
+        }
+    };
+    if (operation === "delete")
+        return;
+    const twoWayFields = fields.filter((field) => isRelationField(field) && field.twoWay);
+    if (options?.noTwoWay)
+        return;
+    for (const field of twoWayFields) {
+        if (!batchSize)
+            throw new Error("VALIDATION_ERROR: batchSize is required");
+        const targetSchema = schema.collections[field.collection];
+        const targetField = getField(targetSchema.fields, field.twoWay);
+        const targetSingleFieldRelations = getSingleFieldRelations(targetSchema, targetSchema.fields);
+        const targetSingleFieldRelationsNames = Array.from(targetSingleFieldRelations).map((field) => field.name);
+        if (!targetField)
+            throw new Error(`SCHEMA_ERROR: Field ${field.twoWay} not found in collection ${field.collection}`);
+        if (isRelationField(targetField)) {
+            if (record[`${field.name}_Array`]) {
+                for (const [id, relation] of Object.entries(record[field.name])) {
+                    if (operation === "update" && originalRecord && originalRecord[`${field.name}_Array`]?.includes(id))
+                        continue;
+                    const finalRecord = { ...originalRecord, ...record };
+                    removeDeleteSentinels(finalRecord);
+                    const includeFields = {};
+                    if (targetField.includeFields) {
+                        targetField.includeFields.forEach((includeField) => {
+                            // eslint-disable-next-line security/detect-object-injection
+                            if (finalRecord[includeField] !== undefined) {
+                                // eslint-disable-next-line security/detect-object-injection
+                                includeFields[includeField] = finalRecord[includeField];
+                                const includeFieldSchema = getField(collectionSchema.fields, includeField);
+                                const lowercaseFields = getLowercaseFields(collectionSchema, [includeFieldSchema]);
+                                if (lowercaseFields.size === 1) {
+                                    includeFields[`${includeField}_Lowercase`] =
+                                        finalRecord[`${includeField}_Lowercase`];
+                                }
+                            }
+                        });
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const fieldUpdate = {
+                        [`${field.twoWay}.${docId}`]: {
+                            Collection_Path: path,
+                            ...includeFields,
+                        },
+                        [`${field.twoWay}_Array`]: arrayUnion(docId),
+                    };
+                    if (targetSingleFieldRelationsNames.includes(targetField.name)) {
+                        fieldUpdate[`${field.twoWay}_Single`] = {
+                            Collection_Path: path,
+                            ...includeFields,
+                        };
+                    }
+                    const systemFields = getRecordSystemFields(record);
+                    batch.update(twoWayIncludeRef(relation.Collection_Path, id), {
+                        ...fieldUpdate,
+                        ...systemFields,
+                    });
+                    batchSize.size++;
+                    if (isDependencyField(targetField, targetSchema, schema)) {
+                        batch.update(twoWayDependencyRef(field, targetField.name, id), {
+                            [`${targetField.name}.${docId}`]: {
+                                Collection_Path: path,
+                                ...includeFields,
+                            },
+                            [`${targetField.name}_Array`]: arrayUnion(docId),
+                        });
+                        batchSize.size++;
+                    }
+                    targetSchema.fields.forEach((targetSchemaField) => {
+                        if (isDependencyField(targetSchemaField, targetSchema, schema)) {
+                            const targetIndexFields = JSON.parse(getFieldNames(getDependencyIndexFields(targetSchemaField, targetSchema, schema)));
+                            const dependencyFieldUpdate = {};
+                            if (targetIndexFields.includes(targetField.name)) {
+                                dependencyFieldUpdate[`${field.twoWay}_Array`] = arrayUnion(docId);
+                            }
+                            Object.keys(systemFields).forEach((systemField) => {
+                                if (targetIndexFields.includes(systemField)) {
+                                    // eslint-disable-next-line security/detect-object-injection
+                                    dependencyFieldUpdate[systemField] = systemFields[systemField];
+                                }
+                            });
+                            if (Object.keys(dependencyFieldUpdate).length > 0) {
+                                batch.update(twoWayDependencyRef(field, targetSchemaField.name, id), dependencyFieldUpdate);
+                                batchSize.size++;
+                            }
+                        }
+                    });
+                    const targetRoleGroups = allRoleGroups[targetSchema.labels.collection];
+                    for (const group of targetRoleGroups) {
+                        if (group.fields.some((groupField) => groupField.name === targetField.name)) {
+                            const groupFieldUpdate = { ...fieldUpdate };
+                            Object.keys(systemFields).forEach((systemField) => {
+                                if (group.fields.some((groupField) => groupField.name === systemField)) {
+                                    // eslint-disable-next-line security/detect-object-injection
+                                    groupFieldUpdate[systemField] = systemFields[systemField];
+                                }
+                            });
+                            if (Object.keys(groupFieldUpdate).length > 0) {
+                                batch.update(twoWayPrivateRef(field, group.key, id), groupFieldUpdate);
+                                batchSize.size++;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else
+            throw new Error(`SCHEMA_ERROR: Invalid field type: ${targetField.type}`);
+    }
+    if (batchSize && batchSize.size > 500) {
+        throw new Error(`VALIDATION_ERROR: The number of operations in the Firestore transaction has exceeded the limit of 500. This is likely due to a large number of two way updates, roles, dependencies on the collection, unique field checks, entity restrictions (in permissions when dealing with user collections) or relation hierarchy checks.`);
+    }
+    for (const field of twoWayFields) {
+        if (!batchSize)
+            throw new Error("VALIDATION_ERROR: batchSize is required");
+        const targetSchema = schema.collections[field.collection];
+        const targetField = getField(targetSchema.fields, field.twoWay);
+        if (!targetField)
+            throw new Error(`SCHEMA_ERROR: Field ${field.twoWay} not found in collection ${field.collection}`);
+        if (isRelationField(targetField)) {
+            if (operation === "update") {
+                if (originalRecord &&
+                    !(record[field.name] && isDeleteSentinel(record[field.name])) &&
+                    record[`${field.name}_Array`] &&
+                    originalRecord[`${field.name}_Array`]?.length > 0) {
+                    for (const [id, relation] of Object.entries(originalRecord[field.name])) {
+                        if (!record[`${field.name}_Array`].includes(id) && !noDelete?.get(field.name)?.includes(id)) {
+                            batchSize.size += getDeleteFieldBatchSize(targetSchema, targetField);
+                            if (batchSize.size <= 500) {
+                                deleteFields(field, targetSchema, targetField, id, relation.Collection_Path);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else
+            throw new Error(`SCHEMA_ERROR: Invalid field type: ${targetField.type}`);
+    }
+    for (const field of twoWayFields) {
+        if (!batchSize)
+            throw new Error("VALIDATION_ERROR: batchSize is required");
+        const targetSchema = schema.collections[field.collection];
+        const targetField = getField(targetSchema.fields, field.twoWay);
+        if (!targetField)
+            throw new Error(`SCHEMA_ERROR: Field ${field.twoWay} not found in collection ${field.collection}`);
+        if (isRelationField(targetField)) {
+            if (operation === "update") {
+                if (originalRecord &&
+                    record[field.name] &&
+                    isDeleteSentinel(record[field.name]) &&
+                    originalRecord[`${field.name}_Array`]?.length > 0) {
+                    for (const [id, relation] of Object.entries(originalRecord[field.name])) {
+                        if (!noDelete?.get(field.name)?.includes(id)) {
+                            batchSize.size += getDeleteFieldBatchSize(targetSchema, targetField);
+                            if (batchSize.size <= 500) {
+                                deleteFields(field, targetSchema, targetField, id, relation.Collection_Path);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else
+            throw new Error(`SCHEMA_ERROR: Invalid field type: ${targetField.type}`);
+    }
+    return;
+};

package/lib/src/operations/removeDeleteSentinels.d.ts

@@ -0,0 +1,2 @@
+import { StokerRecord } from "@stoker-platform/types";
+export declare const removeDeleteSentinels: (obj: StokerRecord) => void;

package/lib/src/operations/removeDeleteSentinels.js

@@ -0,0 +1,15 @@
+import { isDeleteSentinel } from "./isDeleteSentinel.js";
+/* eslint-disable security/detect-object-injection */
+export const removeDeleteSentinels = (obj) => {
+    for (const key in obj) {
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+            continue;
+        }
+        if (isDeleteSentinel(obj[key])) {
+            delete obj[key];
+        }
+        else if (typeof obj[key] === "object" && obj[key] !== null) {
+            removeDeleteSentinels(obj[key]);
+        }
+    }
+};

package/lib/src/operations/removeDeletedFields.d.ts

@@ -0,0 +1,2 @@
+import { StokerRecord } from "@stoker-platform/types";
+export declare const removeDeletedFields: (document: StokerRecord, fieldReferences: Map<unknown, Set<string>>) => void;

package/lib/src/operations/removeDeletedFields.js

@@ -0,0 +1,14 @@
+export const removeDeletedFields = (document, fieldReferences) => {
+    Object.keys(document).forEach((key) => {
+        let hasReference = false;
+        fieldReferences.forEach((fieldReference) => {
+            if (fieldReference.has(key)) {
+                hasReference = true;
+            }
+        });
+        if (!hasReference) {
+            // eslint-disable-next-line security/detect-object-injection
+            delete document[key];
+        }
+    });
+};

package/lib/src/operations/removeEmptyStrings.d.ts

@@ -0,0 +1,2 @@
+import { StokerRecord } from "@stoker-platform/types";
+export declare const removeEmptyStrings: (record: StokerRecord | Partial<StokerRecord>) => void;

package/lib/src/operations/removeEmptyStrings.js

@@ -0,0 +1,14 @@
+/* eslint-disable security/detect-object-injection */
+export const removeEmptyStrings = (record) => {
+    for (const key in record) {
+        if (!Object.prototype.hasOwnProperty.call(record, key)) {
+            continue;
+        }
+        if (record[key] === "") {
+            delete record[key];
+        }
+        else if (typeof record[key] === "object" && record[key] !== null) {
+            removeEmptyStrings(record[key]);
+        }
+    }
+};

package/lib/src/operations/removePrivateFields.d.ts

@@ -0,0 +1,2 @@
+import { CollectionSchema, StokerRecord } from "@stoker-platform/types";
+export declare const removePrivateFields: (record: StokerRecord, schema: CollectionSchema) => StokerRecord;

package/lib/src/operations/removePrivateFields.js

@@ -0,0 +1,14 @@
+import { getField } from "../schema/getField.js";
+import cloneDeep from "lodash/cloneDeep.js";
+export const removePrivateFields = (record, schema) => {
+    const { fields } = schema;
+    const privateFieldsRemoved = cloneDeep(record);
+    Object.keys(record).filter((key) => {
+        const field = getField(fields, key);
+        if (field?.access) {
+            // eslint-disable-next-line security/detect-object-injection
+            delete privateFieldsRemoved[key];
+        }
+    });
+    return privateFieldsRemoved;
+};

package/lib/src/operations/removeUndefined.d.ts

@@ -0,0 +1,2 @@
+import { StokerRecord } from "@stoker-platform/types";
+export declare const removeUndefined: (record: StokerRecord | Partial<StokerRecord>) => void;

package/lib/src/operations/removeUndefined.js

@@ -0,0 +1,14 @@
+/* eslint-disable security/detect-object-injection */
+export const removeUndefined = (record) => {
+    for (const key in record) {
+        if (!Object.prototype.hasOwnProperty.call(record, key)) {
+            continue;
+        }
+        if (record[key] === undefined) {
+            delete record[key];
+        }
+        else if (typeof record[key] === "object" && record[key] !== null) {
+            removeUndefined(record[key]);
+        }
+    }
+};

package/lib/src/operations/retryOperation.d.ts

@@ -0,0 +1 @@
+export declare const retryOperation: (callback: any, args: unknown[], errorCallback?: any, delay?: number) => Promise<void>;

package/lib/src/operations/retryOperation.js

@@ -0,0 +1,21 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const retryOperation = async (callback, args, errorCallback, delay = 1000) => {
+    let retries = 5;
+    while (retries > 0) {
+        try {
+            await callback(...args);
+            break;
+        }
+        catch (error) {
+            retries--;
+            if (retries === 0) {
+                throw error;
+            }
+            if (errorCallback) {
+                errorCallback(error);
+            }
+            await new Promise((res) => setTimeout(res, delay));
+            delay *= 2;
+        }
+    }
+};

package/lib/src/operations/runHooks.d.ts

@@ -0,0 +1,17 @@
+import { CollectionCustomization, PreOperationHookArgs, PreWriteHookArgs, PostWriteHookArgs, PostOperationHookArgs, PreDuplicateHookArgs, PostWriteErrorHookArgs, PreReadHookArgs, PostReadHookArgs, GlobalConfig, PreFileAddHookArgs, PreFileUpdateHookArgs, PostFileAddHookArgs, PostFileUpdateHookArgs } from "@stoker-platform/types";
+export declare function runHooks(hookName: "preOperation", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreOperationHookArgs): Promise<void>;
+export declare function runHooks(hookName: "preRead", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreReadHookArgs): Promise<void>;
+export declare function runHooks(hookName: "postRead", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PostReadHookArgs): Promise<void>;
+export declare function runHooks(hookName: "preOperation", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreOperationHookArgs): Promise<void>;
+export declare function runHooks(hookName: "preDuplicate", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreDuplicateHookArgs): Promise<void>;
+export declare function runHooks(hookName: "preWrite", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreWriteHookArgs): Promise<void>;
+export declare function runHooks(hookName: "postWrite", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PostWriteHookArgs): Promise<void>;
+export declare function runHooks(hookName: "postWriteError", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PostWriteErrorHookArgs): Promise<{
+    resolved: boolean;
+    retry?: boolean;
+} | void>;
+export declare function runHooks(hookName: "postOperation", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PostOperationHookArgs): Promise<void>;
+export declare function runHooks(hookName: "preFileAdd", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreFileAddHookArgs): Promise<void>;
+export declare function runHooks(hookName: "preFileUpdate", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PreFileUpdateHookArgs): Promise<void>;
+export declare function runHooks(hookName: "postFileAdd", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PostFileAddHookArgs): Promise<void>;
+export declare function runHooks(hookName: "postFileUpdate", globalConfig: GlobalConfig, customization: CollectionCustomization, args?: PostFileUpdateHookArgs): Promise<void>;

package/lib/src/operations/runHooks.js

@@ -0,0 +1,18 @@
+import { tryPromise } from "../getConfigValue.js";
+const hook = async (name, callback, args) => {
+    if (callback) {
+        const value = await tryPromise(callback, args);
+        if (value === false)
+            throw new Error(`CANCELLED: Operation cancelled by ${name}`);
+        return value;
+    }
+};
+export async function runHooks(hookName, globalConfig, customization, args) {
+    const value = await hook(hookName, customization.custom?.[hookName], args);
+    for (const field of customization.fields) {
+        await hook(hookName, field.custom?.[hookName], args);
+    }
+    await hook(hookName, globalConfig?.[hookName], args);
+    if (hookName === "postWriteError")
+        return value;
+}

package/lib/src/operations/sanitizeDownloadFilename.d.ts

@@ -0,0 +1 @@
+export declare const sanitizeDownloadFilename: (filename: string) => string;

package/lib/src/operations/sanitizeDownloadFilename.js

@@ -0,0 +1,18 @@
+import { validateStorageName } from "./validateStorageName.js";
+export const sanitizeDownloadFilename = (filename) => {
+    if (!filename || typeof filename !== "string") {
+        return "download";
+    }
+    // Remove control characters
+    // eslint-disable-next-line no-control-regex
+    let cleaned = filename.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, "");
+    cleaned = cleaned.trim();
+    if (!cleaned) {
+        return "download";
+    }
+    const validationError = validateStorageName(cleaned);
+    if (validationError) {
+        return "download";
+    }
+    return cleaned;
+};

package/lib/src/operations/sanitizeEmailInput.d.ts

@@ -0,0 +1,5 @@
+export declare const sanitizeEmailAddress: (input: string | undefined | null) => string;
+export declare const sanitizeEmailAddressArray: (input: string | string[] | undefined | null) => string[];
+export declare const sanitizeEmailAddressOrArray: (input: string | string[] | undefined | null) => string | string[];
+export declare const sanitizeEmailSubject: (input: string | undefined | null) => string;
+export declare const sanitizeEmailBody: (input: string | undefined | null) => string;

package/lib/src/operations/sanitizeEmailInput.js

@@ -0,0 +1,73 @@
+export const sanitizeEmailAddress = (input) => {
+    if (!input || typeof input !== "string") {
+        return "";
+    }
+    // Remove newlines and carriage returns that could be used for SMTP injection
+    let sanitized = input.replace(/[\r\n]/g, "");
+    // Remove null bytes
+    sanitized = sanitized.replace(/\0/g, "");
+    // Remove control characters (except tab)
+    // eslint-disable-next-line no-control-regex
+    sanitized = sanitized.replace(/[\x00-\x08\x0B-\x1F\x7F]/g, "");
+    sanitized = sanitized.trim();
+    // Limit length to prevent buffer overflow attacks
+    const maxLength = 254; // RFC 5321 maximum email length
+    if (sanitized.length > maxLength) {
+        throw new Error("Email address is too long");
+    }
+    return sanitized;
+};
+export const sanitizeEmailAddressArray = (input) => {
+    if (!input) {
+        return [];
+    }
+    const array = Array.isArray(input) ? input : [input];
+    return array.map((email) => sanitizeEmailAddress(email)).filter((email) => email.length > 0);
+};
+export const sanitizeEmailAddressOrArray = (input) => {
+    if (!input) {
+        return "";
+    }
+    if (Array.isArray(input)) {
+        const sanitized = input.map((email) => sanitizeEmailAddress(email)).filter((email) => email.length > 0);
+        return sanitized;
+    }
+    const sanitized = sanitizeEmailAddress(input);
+    return sanitized || "";
+};
+export const sanitizeEmailSubject = (input) => {
+    if (!input || typeof input !== "string") {
+        return "";
+    }
+    // Remove newlines and carriage returns that could be used for header injection
+    let sanitized = input.replace(/[\r\n]/g, " ");
+    // Remove null bytes
+    sanitized = sanitized.replace(/\0/g, "");
+    // Remove control characters (except tab)
+    // eslint-disable-next-line no-control-regex
+    sanitized = sanitized.replace(/[\x00-\x08\x0B-\x1F\x7F]/g, "");
+    sanitized = sanitized.trim();
+    // Limit length to prevent buffer overflow attacks
+    const maxLength = 998; // RFC 5322 maximum header line length
+    if (sanitized.length > maxLength) {
+        throw new Error("Email subject is too long");
+    }
+    return sanitized;
+};
+export const sanitizeEmailBody = (input) => {
+    if (!input || typeof input !== "string") {
+        return "";
+    }
+    // Remove null bytes
+    let sanitized = input.replace(/\0/g, "");
+    // Remove control characters that could be problematic (keep newlines for formatting)
+    // But remove standalone \r\n sequences that could be interpreted as SMTP commands
+    sanitized = sanitized.replace(/\r\n\r\n/g, "\n\n");
+    sanitized = sanitized.replace(/\r\n/g, "\n");
+    // Limit length to prevent buffer overflow attacks
+    const maxLength = 5000000; // 5MB limit for email body
+    if (sanitized.length > maxLength) {
+        throw new Error("Email body is too long");
+    }
+    return sanitized;
+};

package/lib/src/operations/updateFieldReference.d.ts

@@ -0,0 +1,2 @@
+import { StokerRecord } from "@stoker-platform/types";
+export declare const updateFieldReference: (update: StokerRecord, fieldReference: Set<string>) => void;

package/lib/src/operations/updateFieldReference.js

@@ -0,0 +1,14 @@
+export const updateFieldReference = (update, fieldReference) => {
+    const updateKeys = Object.keys(update);
+    fieldReference.forEach((key) => {
+        if (!(key in updateKeys)) {
+            fieldReference.delete(key);
+        }
+    });
+    updateKeys.forEach((key) => {
+        fieldReference.add(key);
+    });
+    if (!fieldReference.has("id")) {
+        fieldReference.add("id");
+    }
+};

package/lib/src/operations/validateRecord.d.ts

@@ -0,0 +1,2 @@
+import { CollectionCustomization, StokerRecord, PreValidateHookArgs, CollectionSchema, CollectionsSchema } from "@stoker-platform/types";
+export declare const validateRecord: (operation: "create" | "update", record: StokerRecord, collection: CollectionSchema, customization: CollectionCustomization, args: PreValidateHookArgs, schema: CollectionsSchema) => Promise<StokerRecord>;

package/lib/src/operations/validateRecord.js

@@ -0,0 +1,18 @@
+import { getZodSchema } from "./getZodSchema.js";
+import { tryPromise } from "../getConfigValue.js";
+const preValidate = async (callback, args) => {
+    if (callback) {
+        const validation = await tryPromise(callback, args);
+        if (!validation.valid)
+            throw new Error(`VALIDATION_ERROR: ${validation.message}`);
+    }
+};
+export const validateRecord = async (operation, record, collection, customization, args, schema) => {
+    await preValidate(customization.custom?.preValidate, args);
+    for (const field of customization.fields) {
+        await preValidate(field.custom?.preValidate, args);
+    }
+    const zodSchema = getZodSchema(operation, collection, schema);
+    zodSchema.parse(record);
+    return record;
+};

package/lib/src/operations/validateStorageName.d.ts

@@ -0,0 +1 @@
+export declare const validateStorageName: (name: string) => string | null;

package/lib/src/operations/validateStorageName.js

@@ -0,0 +1,19 @@
+export const validateStorageName = (name) => {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return "Name cannot be empty";
+    if (trimmed.includes("/"))
+        return "Name cannot contain /";
+    if (/[\r\n]/.test(trimmed))
+        return "Name cannot contain line breaks";
+    if (/[#[\]*?]/.test(trimmed))
+        return "Name cannot contain any of # [ ] * ?";
+    if (trimmed.includes(".."))
+        return "Name cannot contain ..";
+    if (trimmed === ".")
+        return "Name cannot be .";
+    const byteLength = new TextEncoder().encode(trimmed).length;
+    if (byteLength > 1024)
+        return "Name must be at most 1024 bytes";
+    return null;
+};

package/lib/src/schema/getAccessFields.d.ts

@@ -0,0 +1,2 @@
+import type { CollectionField, CollectionSchema, StokerRole } from "@stoker-platform/types";
+export declare const getAccessFields: (collection: CollectionSchema, role: StokerRole) => CollectionField[];