lucid-extension-sdk 0.0.408 → 0.0.410

package/core/validators/compactvalidatorsandpruners.d.ts

@@ -6,7 +6,7 @@ type ObjectAttributeType = keyof any;
 /**
  * A generic type for a Validator that narrows FROM to TO.
  */
-type Validator<TO extends FROM, FROM = unknown> = (unknownVariable: FROM) => unknownVariable is TO;
+export type Validator<TO extends FROM, FROM = unknown> = (unknownVariable: FROM) => unknownVariable is TO;
 /**
  * A record that maps each key in an object to its respective ValidatorWithOptionalPruner.
  */
@@ -16,7 +16,7 @@ type ObjectValidatorConfig = Record<ObjectAttributeType, ValidatorWithOptionalPr
  *   - prunerResult: The pruned data (or possibly the same data if no pruning is needed) which also constains
  *                   invalidFields: a map of invalid fields (represented by keys) to their original invalid values.
  */
-type Pruner = (unprunedData: unknown) => PrunerResult;
+export type Pruner = (unprunedData: unknown) => PrunerResult;
 /**
  * The result object returned from a pruner function.
  */
@@ -30,11 +30,11 @@ export interface PrunerResult {
  * - `validator` is the function used to validate the data.
  * - `pruner` can optionally used to prune invalid data fields if validation fails.
  */
-interface ValidatorWithOptionalPruner<TO = unknown> {
+export interface ValidatorWithOptionalPruner<TO = unknown> {
     'validator': Validator<TO>;
     'pruner'?: Pruner;
 }
-interface ValidatorWithPruner<TO = unknown> {
+export interface ValidatorWithPruner<TO = unknown> {
     'validator': Validator<TO>;
     'pruner': Pruner;
 }
@@ -51,19 +51,21 @@ type ExtractValidatedTypeFromConfig<V> = V extends {
 type ObjectValidatorToValidatedType<T extends ObjectValidatorConfig> = WithUndefinedAsOptional<{
     [K in keyof T]: ExtractValidatedTypeFromConfig<T[K]>;
 }>;
+type Primitive = string | number | boolean | null | undefined | symbol | bigint;
+type ExcludedTypes = ((...args: any[]) => any) | Primitive | Date;
 /**
  * Recursively applies a "prettifying" transformation to the inferred object type.
  * - For functions, it leaves them as-is.
  * - For objects, it recurses down into properties.
  * - Otherwise, returns the type unchanged.
  */
-type PrettifyDeep<T> = T extends (...args: any[]) => any ? T : T extends object ? {
+type PrettifyDeep<T> = T extends ExcludedTypes ? T : T extends object ? {
     [K in keyof T]: PrettifyDeep<T[K]>;
 } : T;
 /**
  * Extracts the final type from @param ObjectValidatorConfig
  */
-type PrettifiedObjectValidatorType<T extends ObjectValidatorConfig> = PrettifyDeep<ObjectValidatorToValidatedType<T>>;
+export type PrettifiedObjectValidatorType<T extends ObjectValidatorConfig> = PrettifyDeep<ObjectValidatorToValidatedType<T>>;
 export type ExtractValidatedTypeFromValidator<V extends Validator<unknown>> = V extends Validator<infer U> ? U : never;
 /**
  * Creates a validator and pruner for an object.
@@ -85,6 +87,14 @@ export declare function getObjectValidatorAndPruner<T extends ObjectValidatorCon
  * @returns ValidatorWithPruner for the array.
  */
 export declare function getArrayValidatorAndPruner<ElementType>(arrayElementConfig: ValidatorWithOptionalPruner<ElementType> | Validator<ElementType>): ValidatorWithPruner<ElementType[]>;
+/**
+ * Creates a validator and pruner for objects keyed by K and valued by T.
+ *
+ * @param valueConfig   Validator (and optional pruner) for each object's value.
+ * @param keyConfig     Validator (and optional pruner) for each object's key.
+ * @returns             A ValidatorWithPruner for a Record<K, T>.
+ */
+export declare function getObjectOfValidatorAndPruner<T, K extends string | number | symbol = string>(valueConfig: ValidatorWithOptionalPruner<T> | Validator<T>, keyValidator?: Validator<K>): ValidatorWithPruner<Record<K, T>>;
 /**
  * Function used in objectFieldConfig and arrayElementConfig to speficy that invalid
  * items must be pruned/marked as undefined.
@@ -92,20 +102,44 @@ export declare function getArrayValidatorAndPruner<ElementType>(arrayElementConf
  */
 export declare const pruneElement: (element: unknown) => PrunerResult;
 /**
- * Combines a "per-element pruner" for an array’s elements with an "entire array pruner."
+ * Selects and applies one of two pruners based on whether the input data is an array.
+ *
+ * This function acts as a router. If the input `data` is an array, it delegates the pruning
+ * task to the `prunerForArray`. If the input `data` is *not* an array (e.g., could be null,
+ * a string, an object, etc.), it delegates to the `prunerForNonArray`.
+ *
+ * Use Case: This is useful when you need distinct pruning logic depending on whether you
+ * received an array or something else entirely at a specific point in your data structure.
+ * For instance, you might have a pruner designed to process arrays (perhaps iterating
+ * through elements) and another pruner designed to handle scalar values or objects that
+ * might appear in the same data field.
+ *
+ * @param prunerForArray The Pruner function to execute if the input `data` is an array.
+ * This pruner is responsible for handling the entire array data.
+ * @param prunerForNonArray The Pruner function to execute if the input `data` is *not* an array.
+ * @returns A new Pruner function that implements this conditional logic.
+ */
+export declare function selectPrunerByArrayType(prunerForArray: Pruner, prunerForNonArray: Pruner): Pruner;
+/**
+ * Selects and applies one of two pruners based on whether the input data is an object.
  *
- * - If the incoming data is not an array, it applies the `wholeArrayPruner`.
- * - If it is an array, it applies the `perElementPruner` to each element.
+ * This function acts as a router. If the input `data` is an object it delegates the
+ * pruning task to the `prunerForObject`. If the input `data` is *not*
+ * an object (e.g., could be null, an array, a string, a number, etc.), it delegates
+ * to the `prunerForNonObject`.
  *
- * This is useful when you have specialized logic for array-level pruning
- * (e.g., removing the entire array if it fails some overarching condition)
- * but still want to prune individual elements if possible.
+ * Use Case: Similar to `selectPrunerByArrayType`, this is useful for applying different
+ * pruning strategies based on whether the data at a certain point is an object or some other
+ * type. For example, within an array pruner you can use this to apply an object pruner
+ * if an element is an object, but use a simpler pruner (like `pruneElement` which will
+ * remove `null` or invalid types) if the element is not an object.
  *
- * @param perElementPruner A pruner for each element in the array.
- * @param wholeArrayPruner A pruner for the entire array.
- * @returns A Pruner that handles both array-level and element-level pruning.
+ * @param prunerForObject The Pruner function to execute if the input `data` is an object.
+ * This pruner is responsible for handling the entire object data.
+ * @param prunerForNonObject The Pruner function to execute if the input `data` is *not* an object.
+ * @returns A new Pruner function that implements this conditional logic.
  */
-export declare function liftArrayPruner(perElementPruner: Pruner, wholeArrayPruner: Pruner): Pruner;
+export declare function selectPrunerByObjectType(prunerForObject: Pruner, prunerForNonObject: Pruner): Pruner;
 /**
  * Helper function to easily create a `ValidatorWithOptionalPruner`.
  *

package/core/validators/compactvalidatorsandpruners.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getValidatorPrunerConfig = exports.liftArrayPruner = exports.pruneElement = exports.getArrayValidatorAndPruner = exports.getObjectValidatorAndPruner = void 0;
+exports.getValidatorPrunerConfig = exports.selectPrunerByObjectType = exports.selectPrunerByArrayType = exports.pruneElement = exports.getObjectOfValidatorAndPruner = exports.getArrayValidatorAndPruner = exports.getObjectValidatorAndPruner = void 0;
 const checks_1 = require("../checks");
 function getValidatorFromConfig(validatorConfig) {
     if ('validator' in validatorConfig) {
@@ -115,6 +115,56 @@ function getArrayValidatorAndPruner(arrayElementConfig) {
     return { validator: arrayValidatorFunction, pruner: arrayPrunerFunction };
 }
 exports.getArrayValidatorAndPruner = getArrayValidatorAndPruner;
+/**
+ * Creates a validator and pruner for objects keyed by K and valued by T.
+ *
+ * @param valueConfig   Validator (and optional pruner) for each object's value.
+ * @param keyConfig     Validator (and optional pruner) for each object's key.
+ * @returns             A ValidatorWithPruner for a Record<K, T>.
+ */
+function getObjectOfValidatorAndPruner(valueConfig, keyValidator = (key) => true) {
+    const valueValidator = getValidatorFromConfig(valueConfig);
+    const valuePruner = getPrunerFromConfig(valueConfig);
+    const objectOfValidator = (subject) => {
+        if ((0, checks_1.isArray)(subject) || !(0, checks_1.isObjectUnsafe)(subject)) {
+            return false;
+        }
+        return Object.entries(subject).every(([k, v]) => keyValidator(k) && valueValidator(v));
+    };
+    const objectOfPruner = (subject) => {
+        if ((0, checks_1.isArray)(subject) || !(0, checks_1.isObjectUnsafe)(subject)) {
+            return {
+                prunerResult: subject,
+                invalidFields: createElementInvalidField(subject),
+            };
+        }
+        const invalidFields = new Map();
+        const prunerResult = Object.assign({}, subject);
+        Object.entries(prunerResult).forEach(([k, v]) => {
+            if (!keyValidator(k)) {
+                invalidFields.set(`key:${k}`, v);
+                // If the key is invalid, we remove the key-value pair from the object.
+                prunerResult[k] = undefined;
+                return;
+            }
+            if (!valueValidator(v)) {
+                if (!valuePruner) {
+                    invalidFields.set(k, v);
+                }
+                else {
+                    const valPrunerResult = valuePruner(v);
+                    prunerResult[k] = valPrunerResult.prunerResult;
+                    for (const [subKey, subVal] of valPrunerResult.invalidFields) {
+                        invalidFields.set(`${k}.${subKey}`, subVal);
+                    }
+                }
+            }
+        });
+        return { prunerResult, invalidFields };
+    };
+    return { validator: objectOfValidator, pruner: objectOfPruner };
+}
+exports.getObjectOfValidatorAndPruner = getObjectOfValidatorAndPruner;
 /**
  * Creates a Map signifying that the entire `element` was invalid,
  * with a key of `""` or some placeholder to represent the entire item.
@@ -132,28 +182,68 @@ const pruneElement = (element) => {
 };
 exports.pruneElement = pruneElement;
 /**
- * Combines a "per-element pruner" for an array’s elements with an "entire array pruner."
+ * Selects and applies one of two pruners based on whether the input data is an array.
+ *
+ * This function acts as a router. If the input `data` is an array, it delegates the pruning
+ * task to the `prunerForArray`. If the input `data` is *not* an array (e.g., could be null,
+ * a string, an object, etc.), it delegates to the `prunerForNonArray`.
+ *
+ * Use Case: This is useful when you need distinct pruning logic depending on whether you
+ * received an array or something else entirely at a specific point in your data structure.
+ * For instance, you might have a pruner designed to process arrays (perhaps iterating
+ * through elements) and another pruner designed to handle scalar values or objects that
+ * might appear in the same data field.
+ *
+ * @param prunerForArray The Pruner function to execute if the input `data` is an array.
+ * This pruner is responsible for handling the entire array data.
+ * @param prunerForNonArray The Pruner function to execute if the input `data` is *not* an array.
+ * @returns A new Pruner function that implements this conditional logic.
+ */
+function selectPrunerByArrayType(prunerForArray, prunerForNonArray) {
+    return (data) => {
+        if ((0, checks_1.isArray)(data)) {
+            // Data is an array, apply the pruner designated for arrays.
+            return prunerForArray(data);
+        }
+        else {
+            // Data is not an array, apply the pruner designated for non-arrays.
+            return prunerForNonArray(data);
+        }
+    };
+}
+exports.selectPrunerByArrayType = selectPrunerByArrayType;
+/**
+ * Selects and applies one of two pruners based on whether the input data is an object.
  *
- * - If the incoming data is not an array, it applies the `wholeArrayPruner`.
- * - If it is an array, it applies the `perElementPruner` to each element.
+ * This function acts as a router. If the input `data` is an object it delegates the
+ * pruning task to the `prunerForObject`. If the input `data` is *not*
+ * an object (e.g., could be null, an array, a string, a number, etc.), it delegates
+ * to the `prunerForNonObject`.
  *
- * This is useful when you have specialized logic for array-level pruning
- * (e.g., removing the entire array if it fails some overarching condition)
- * but still want to prune individual elements if possible.
+ * Use Case: Similar to `selectPrunerByArrayType`, this is useful for applying different
+ * pruning strategies based on whether the data at a certain point is an object or some other
+ * type. For example, within an array pruner you can use this to apply an object pruner
+ * if an element is an object, but use a simpler pruner (like `pruneElement` which will
+ * remove `null` or invalid types) if the element is not an object.
  *
- * @param perElementPruner A pruner for each element in the array.
- * @param wholeArrayPruner A pruner for the entire array.
- * @returns A Pruner that handles both array-level and element-level pruning.
+ * @param prunerForObject The Pruner function to execute if the input `data` is an object.
+ * This pruner is responsible for handling the entire object data.
+ * @param prunerForNonObject The Pruner function to execute if the input `data` is *not* an object.
+ * @returns A new Pruner function that implements this conditional logic.
  */
-function liftArrayPruner(perElementPruner, wholeArrayPruner) {
+function selectPrunerByObjectType(prunerForObject, prunerForNonObject) {
     return (data) => {
-        if (!(0, checks_1.isArray)(data)) {
-            return wholeArrayPruner(data);
+        if ((0, checks_1.isObjectUnsafe)(data)) {
+            // Data is an object, apply the pruner designated for objects.
+            return prunerForObject(data);
+        }
+        else {
+            // Data is not an object, apply the pruner designated for non-objects.
+            return prunerForNonObject(data);
         }
-        return perElementPruner(data);
     };
 }
-exports.liftArrayPruner = liftArrayPruner;
+exports.selectPrunerByObjectType = selectPrunerByObjectType;
 /**
  * Helper function to easily create a `ValidatorWithOptionalPruner`.
  *

package/dataconnector/datasourceupdatetypes.d.ts

@@ -58,6 +58,7 @@ export interface SerializedCollectionPatch {
     'itemsPatch': SerializedItemsPatch;
     'properties'?: serializedPropertiesForApi;
 }
+/** Represents a standard, incremental update to a collection. */
 export declare class ItemsPatchInexhaustive {
     /**
      * Items to be added or changed in the collection. Mapping from item serialized primary key to
@@ -78,6 +79,7 @@ export declare class ItemsPatchInexhaustive {
     /** Items to remove from the collection, based on the same primary key algorithm. */
     itemsDeleted?: string[] | undefined, errors?: Map<string, SerializedLucidDictionary> | undefined, fieldConstraintsPerItem?: Map<string, Map<string, FieldConstraintDefinition[]>> | undefined);
 }
+/** Sets the collection to exactly the items in this patch, deleting all others. */
 export declare class ItemsPatchExhaustive {
     items: Map<string, SerializedFields>;
     rekeyingMap?: Map<string, string | null> | undefined;
@@ -87,6 +89,7 @@ export declare class ItemsPatchExhaustive {
     private readonly _brand;
     constructor(items: Map<string, SerializedFields>, rekeyingMap?: Map<string, string | null> | undefined, fieldNamesChanged?: Map<string, string | null> | undefined, errors?: Map<string, SerializedLucidDictionary> | undefined, fieldConstraintsPerItem?: Map<string, Map<string, FieldConstraintDefinition[]>> | undefined);
 }
+/** The anonymous type is kept for backward compatibility; use ItemsPatchInexhaustive instead. */
 export type ItemsPatch = {
     /**
      * Items to be added or changed in the collection. Mapping from item serialized primary key to

package/dataconnector/datasourceupdatetypes.js

@@ -5,6 +5,7 @@ const checks_1 = require("../core/checks");
 const fieldtypedefinition_1 = require("../core/data/fieldtypedefinition/fieldtypedefinition");
 const object_1 = require("../core/object");
 const collectionerrortypes_1 = require("../data/collectionerrortypes");
+/** Represents a standard, incremental update to a collection. */
 class ItemsPatchInexhaustive {
     constructor(
     /**
@@ -22,6 +23,7 @@ class ItemsPatchInexhaustive {
     }
 }
 exports.ItemsPatchInexhaustive = ItemsPatchInexhaustive;
+/** Sets the collection to exactly the items in this patch, deleting all others. */
 class ItemsPatchExhaustive {
     constructor(items, rekeyingMap, fieldNamesChanged, errors, fieldConstraintsPerItem) {
         this.items = items;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.408",
+    "version": "0.0.410",
     "description": "Utility classes for writing Lucid Software editor extensions",
     "main": "index.js",
     "types": "index.d.ts",