@land-catalyst/batch-data-sdk 1.1.12 → 1.1.19

package/dist/property-field/utils.js

@@ -0,0 +1,479 @@
+"use strict";
+/**
+ * Property Field Utilities
+ *
+ * Utilities for working with property field paths and metadata
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPropertyFieldMetadata = getPropertyFieldMetadata;
+exports.getPropertyFieldValue = getPropertyFieldValue;
+exports.getPropertyGroupFields = getPropertyGroupFields;
+exports.getNestedFieldMetadata = getNestedFieldMetadata;
+exports.isValidPropertyField = isValidPropertyField;
+exports.getPropertyGroupFieldPaths = getPropertyGroupFieldPaths;
+exports.getPropertyFieldDescription = getPropertyFieldDescription;
+exports.getPropertyFieldType = getPropertyFieldType;
+exports.mapSearchCriteriaToPropertyPath = mapSearchCriteriaToPropertyPath;
+exports.getSearchCriteriaFieldMetadata = getSearchCriteriaFieldMetadata;
+exports.getSearchCriteriaMetadata = getSearchCriteriaMetadata;
+exports.getSearchCriteriaFieldsForPropertyGroup = getSearchCriteriaFieldsForPropertyGroup;
+exports.getSearchCriteriaFieldsWithMetadata = getSearchCriteriaFieldsWithMetadata;
+exports.getSearchCriteriaMetadataForGroup = getSearchCriteriaMetadataForGroup;
+exports.extractSearchCriteriaFieldPaths = extractSearchCriteriaFieldPaths;
+exports.getSearchCriteriaFieldsMetadata = getSearchCriteriaFieldsMetadata;
+exports.getPropertyFieldsMetadata = getPropertyFieldsMetadata;
+const metadata_1 = require("./metadata");
+/**
+ * Get metadata for a property field by its path
+ * @param fieldPath The field path (e.g., "address.city", "owner.fullName")
+ * @returns The field metadata, or undefined if not found
+ * @example
+ * ```typescript
+ * const cityMeta = getPropertyFieldMetadata("address.city");
+ * console.log(cityMeta?.description); // "The city (e.g. Chicago)"
+ * ```
+ */
+function getPropertyFieldMetadata(fieldPath) {
+    return (0, metadata_1.getFieldMetadata)(fieldPath);
+}
+/**
+ * Get the value at a field path from a property object
+ * @param property The property object
+ * @param fieldPath The field path (e.g., "address.city", "owner.fullName")
+ * @returns The value at the path, or undefined if not found
+ * @example
+ * ```typescript
+ * const city = getPropertyFieldValue(property, "address.city");
+ * ```
+ */
+function getPropertyFieldValue(property, fieldPath) {
+    const parts = fieldPath.split(".");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let value = property;
+    for (const part of parts) {
+        if (value == null) {
+            return undefined;
+        }
+        // Handle array notation like "[n]"
+        if (part === "[n]") {
+            // This is an array element - return the array itself
+            continue;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        value = value[part];
+    }
+    return value;
+}
+/**
+ * Get metadata for all fields in a response group
+ * @param groupName The response group name (e.g., "address", "owner", "building")
+ * @returns Array of field metadata for that group
+ * @example
+ * ```typescript
+ * const addressFields = getPropertyGroupFields("address");
+ * // Returns all fields under address.*
+ * ```
+ */
+function getPropertyGroupFields(groupName) {
+    return Object.values(metadata_1.PROPERTY_FIELD_METADATA).filter((field) => field.responseGroupName === groupName);
+}
+/**
+ * Get metadata for a nested field path
+ * Handles nested paths like "owner.mailingAddress.city"
+ * @param fieldPath The full field path
+ * @returns The field metadata, or undefined if not found
+ */
+function getNestedFieldMetadata(fieldPath) {
+    return (0, metadata_1.getFieldMetadata)(fieldPath);
+}
+/**
+ * Type guard to check if a field path exists in metadata
+ * @param fieldPath The field path to check
+ * @returns True if the field exists in metadata
+ */
+function isValidPropertyField(fieldPath) {
+    return fieldPath in metadata_1.PROPERTY_FIELD_METADATA;
+}
+/**
+ * Get all field paths for a specific property group
+ * @param groupName The response group name
+ * @returns Array of field paths
+ */
+function getPropertyGroupFieldPaths(groupName) {
+    return Object.values(metadata_1.PROPERTY_FIELD_METADATA)
+        .filter((field) => field.responseGroupName === groupName)
+        .map((field) => field.fieldPath);
+}
+/**
+ * Get field description for a property field
+ * @param fieldPath The field path
+ * @returns The description, or undefined if not found
+ */
+function getPropertyFieldDescription(fieldPath) {
+    return (0, metadata_1.getFieldMetadata)(fieldPath)?.description;
+}
+/**
+ * Get field data type for a property field
+ * @param fieldPath The field path
+ * @returns The data type, or undefined if not found
+ */
+function getPropertyFieldType(fieldPath) {
+    return (0, metadata_1.getFieldMetadata)(fieldPath)?.dataType;
+}
+/**
+ * Map a SearchCriteria field path to its corresponding Property field path
+ * Most SearchCriteria fields map directly to Property fields (e.g., "address.city" -> "address.city")
+ * @param searchCriteriaPath The field path in SearchCriteria (e.g., "address.city", "building.yearBuilt")
+ * @returns The corresponding Property field path, or undefined if no mapping exists
+ * @example
+ * ```typescript
+ * const propertyPath = mapSearchCriteriaToPropertyPath("address.city");
+ * // Returns "address.city"
+ *
+ * const propertyPath = mapSearchCriteriaToPropertyPath("building.yearBuilt");
+ * // Returns "building.yearBuilt"
+ * ```
+ */
+function mapSearchCriteriaToPropertyPath(searchCriteriaPath) {
+    // Most SearchCriteria paths map directly to Property paths
+    // The field names are the same, just used in different contexts
+    // Examples:
+    // - SearchCriteria.address.city -> Property.address.city
+    // - SearchCriteria.building.yearBuilt -> Property.building.yearBuilt
+    // - SearchCriteria.assessment.assessmentYear -> Property.assessment.assessmentYear (if exists)
+    // Check if the path exists in Property metadata
+    if (searchCriteriaPath in metadata_1.PROPERTY_FIELD_METADATA) {
+        return searchCriteriaPath;
+    }
+    // If not found, return undefined to indicate no mapping exists
+    // The caller can use this to determine if there's a Property field mapping
+    return undefined;
+}
+/**
+ * Get Property field metadata for a SearchCriteria field path
+ * This helps users understand what Property field they're filtering on
+ * @param searchCriteriaPath The field path in SearchCriteria (e.g., "address.city", "building.yearBuilt")
+ * @returns The Property field metadata, or undefined if not found
+ * @example
+ * ```typescript
+ * // When building a search criteria, see what Property field you're filtering on
+ * const metadata = getSearchCriteriaFieldMetadata("address.city");
+ * console.log(metadata?.description); // "The city (e.g. Chicago)"
+ * console.log(metadata?.dataType); // "string"
+ *
+ * const builder = new AddressSearchCriteriaBuilder();
+ * builder.city((c) => {
+ *   // You're filtering on Property.address.city
+ *   const meta = getSearchCriteriaFieldMetadata("address.city");
+ *   console.log(`Filtering on: ${meta?.description}`);
+ *   c.equals("Phoenix");
+ * });
+ * ```
+ */
+function getSearchCriteriaFieldMetadata(searchCriteriaPath) {
+    const propertyPath = mapSearchCriteriaToPropertyPath(searchCriteriaPath);
+    if (!propertyPath) {
+        return undefined;
+    }
+    return (0, metadata_1.getFieldMetadata)(propertyPath);
+}
+/**
+ * Get SearchCriteria field metadata inferred from Property field metadata
+ * This creates a SearchCriteria-specific metadata object that references the Property field
+ * @param searchCriteriaPath The field path in SearchCriteria (e.g., "address.city", "building.yearBuilt")
+ * @returns SearchCriteria field metadata with Property field information
+ * @example
+ * ```typescript
+ * // Get metadata for a SearchCriteria field, even if it doesn't map exactly
+ * const scMetadata = getSearchCriteriaMetadata("address.city");
+ * console.log(scMetadata.description); // "Filter on: The city (e.g. Chicago)"
+ * console.log(scMetadata.propertyPath); // "address.city"
+ * console.log(scMetadata.hasPropertyMapping); // true
+ *
+ * // Works even for fields that might not have exact Property mappings
+ * const scMetadata2 = getSearchCriteriaMetadata("assessment.assessmentYear");
+ * if (scMetadata2.hasPropertyMapping) {
+ *   console.log(`Filtering on: ${scMetadata2.propertyMetadata?.description}`);
+ * }
+ * ```
+ */
+function getSearchCriteriaMetadata(searchCriteriaPath) {
+    const propertyPath = mapSearchCriteriaToPropertyPath(searchCriteriaPath);
+    const propertyMetadata = propertyPath
+        ? (0, metadata_1.getFieldMetadata)(propertyPath)
+        : undefined;
+    // Generate description based on Property metadata
+    let description;
+    if (propertyMetadata) {
+        // If we have Property metadata, create a description that explains
+        // this SearchCriteria field filters on that Property field
+        description = `Filter on: ${propertyMetadata.description}`;
+    }
+    else {
+        // If no Property metadata, create a generic description
+        const parts = searchCriteriaPath.split(".");
+        const fieldName = parts[parts.length - 1] || searchCriteriaPath;
+        description = `Filter on ${fieldName} field`;
+    }
+    return {
+        searchCriteriaPath,
+        propertyPath,
+        propertyMetadata: propertyMetadata || undefined,
+        hasPropertyMapping: propertyMetadata !== undefined,
+        description,
+        propertyDataType: propertyMetadata?.dataType,
+        dataset: propertyMetadata?.dataset,
+    };
+}
+/**
+ * Get all SearchCriteria field paths that map to a specific Property response group
+ * @param propertyGroupName The Property response group name (e.g., "address", "owner", "building")
+ * @returns Array of SearchCriteria field paths that filter on fields in that group
+ * @example
+ * ```typescript
+ * // Get all SearchCriteria fields that filter on address fields
+ * const addressSearchFields = getSearchCriteriaFieldsForPropertyGroup("address");
+ * // Returns: ["address.street", "address.city", "address.state", ...]
+ * ```
+ */
+function getSearchCriteriaFieldsForPropertyGroup(propertyGroupName) {
+    // Get all Property fields in this group
+    const propertyFields = getPropertyGroupFields(propertyGroupName);
+    // Map them to SearchCriteria paths (usually 1:1)
+    return propertyFields.map((field) => field.fieldPath);
+}
+function getSearchCriteriaFieldsWithMetadata(propertyGroupName) {
+    const propertyFields = getPropertyGroupFields(propertyGroupName);
+    return propertyFields.map((field) => ({
+        searchCriteriaPath: field.fieldPath,
+        propertyPath: field.fieldPath,
+        metadata: field,
+    }));
+}
+/**
+ * Get SearchCriteria metadata for all fields in a Property response group
+ * @param propertyGroupName The Property response group name (e.g., "address", "owner", "building")
+ * @returns Array of SearchCriteria field metadata objects
+ * @example
+ * ```typescript
+ * // Get all address-related SearchCriteria fields with inferred metadata
+ * const addressFields = getSearchCriteriaMetadataForGroup("address");
+ * // Returns SearchCriteriaFieldMetadata[] with descriptions like
+ * // "Filter on: The city (e.g. Chicago)"
+ * ```
+ */
+function getSearchCriteriaMetadataForGroup(propertyGroupName) {
+    const propertyFields = getPropertyGroupFields(propertyGroupName);
+    return propertyFields.map((field) => getSearchCriteriaMetadata(field.fieldPath));
+}
+/**
+ * Extract all field paths from a SearchCriteria object
+ * Recursively walks through the SearchCriteria structure and collects all field paths
+ * @param searchCriteria The SearchCriteria object to analyze
+ * @param prefix Optional prefix for nested paths (used internally for recursion)
+ * @returns Array of field paths found in the SearchCriteria
+ * @example
+ * ```typescript
+ * const criteria = {
+ *   address: { city: { equals: "Phoenix" }, state: { equals: "AZ" } },
+ *   building: { yearBuilt: { min: 1990, max: 2020 } }
+ * };
+ * const paths = extractSearchCriteriaFieldPaths(criteria);
+ * // Returns: ["address.city", "address.state", "building.yearBuilt"]
+ * ```
+ */
+function extractSearchCriteriaFieldPaths(searchCriteria, prefix = "") {
+    const paths = [];
+    function processValue(value, currentPath) {
+        if (value == null) {
+            return;
+        }
+        // Check if this is a filter object (StringFilter, NumericRangeFilter, etc.)
+        if (typeof value === "object" && !Array.isArray(value)) {
+            const obj = value;
+            const filterKeys = [
+                "equals",
+                "contains",
+                "startsWith",
+                "endsWith",
+                "inList",
+                "notInList",
+                "matches",
+                "min",
+                "max",
+                "minDate",
+                "maxDate",
+            ];
+            const isFilterObject = filterKeys.some((key) => key in obj);
+            if (isFilterObject) {
+                // This is a filter object, so the current path is the field path
+                if (currentPath) {
+                    paths.push(currentPath);
+                }
+                return; // Don't recurse into filter objects
+            }
+            // It's a nested criteria object, process its properties
+            for (const [key, val] of Object.entries(obj)) {
+                // Skip special fields
+                if (key === "query" ||
+                    key === "quickList" ||
+                    key === "quickLists" ||
+                    key === "orQuickLists" ||
+                    key === "or") {
+                    continue;
+                }
+                const fieldPath = currentPath ? `${currentPath}.${key}` : key;
+                processValue(val, fieldPath);
+            }
+        }
+        else if (Array.isArray(value)) {
+            // Handle arrays (like orQuickLists, or criteria)
+            value.forEach((item, index) => {
+                if (typeof item === "object" && item !== null) {
+                    processValue(item, `${currentPath}[${index}]`);
+                }
+            });
+        }
+    }
+    // Start processing
+    for (const [key, value] of Object.entries(searchCriteria)) {
+        // Skip special top-level fields
+        if (key === "query" ||
+            key === "quickList" ||
+            key === "quickLists" ||
+            key === "orQuickLists" ||
+            key === "or") {
+            continue;
+        }
+        const fieldPath = prefix ? `${prefix}.${key}` : key;
+        processValue(value, fieldPath);
+    }
+    return paths;
+}
+/**
+ * Get metadata for all fields present in a SearchCriteria object
+ * Extracts all field paths and generates metadata for each one
+ * @param searchCriteria The SearchCriteria object to analyze
+ * @returns Array of SearchCriteria field metadata for all fields found
+ * @example
+ * ```typescript
+ * const criteria = new SearchCriteriaBuilder("US")
+ *   .address((a) => {
+ *     a.city((c) => c.equals("Phoenix"))
+ *       .state((s) => s.equals("AZ"));
+ *   })
+ *   .building((b) => {
+ *     b.yearBuilt((y) => y.min(1990).max(2020));
+ *   })
+ *   .build();
+ *
+ * const metadata = getSearchCriteriaFieldsMetadata(criteria);
+ * // Returns metadata for address.city, address.state, building.yearBuilt
+ * ```
+ */
+function getSearchCriteriaFieldsMetadata(searchCriteria) {
+    const fieldPaths = extractSearchCriteriaFieldPaths(searchCriteria);
+    return fieldPaths.map((path) => getSearchCriteriaMetadata(path));
+}
+/**
+ * Get metadata for all fields present in a property object
+ * Recursively iterates through the property object and collects metadata for each field.
+ *
+ * Note: This function is designed for Property response objects, not SearchCriteria.
+ * The metadata describes Property response fields (their types, descriptions, datasets),
+ * which are different from SearchCriteria filter objects.
+ *
+ * @param property The property object to analyze
+ * @param prefix Optional prefix for nested paths (used internally for recursion)
+ * @returns Array of field metadata entries
+ * @example
+ * ```typescript
+ * const property = {
+ *   address: { city: "Phoenix", state: "AZ" },
+ *   owner: { fullName: "John Doe" }
+ * };
+ * const metadata = getPropertyFieldsMetadata(property);
+ * // Returns metadata for address.city, address.state, owner.fullName
+ * ```
+ */
+function getPropertyFieldsMetadata(property, prefix = "") {
+    const entries = [];
+    // Helper function to recursively process objects
+    function processValue(value, currentPath, depth = 0) {
+        // Limit recursion depth to prevent infinite loops
+        if (depth > 10) {
+            return;
+        }
+        if (value == null) {
+            return;
+        }
+        // Handle arrays
+        if (Array.isArray(value)) {
+            // For arrays, check if there's metadata for the array element pattern
+            const arrayPath = currentPath ? `${currentPath}.[n]` : "[n]";
+            const arrayMetadata = (0, metadata_1.getFieldMetadata)(arrayPath);
+            if (arrayMetadata) {
+                entries.push({
+                    fieldPath: currentPath || arrayPath,
+                    value: value,
+                    metadata: arrayMetadata,
+                    hasMetadata: true,
+                });
+            }
+            // Process each element in the array
+            value.forEach((item, index) => {
+                if (typeof item === "object" && item !== null) {
+                    processValue(item, `${currentPath}.[${index}]`, depth + 1);
+                }
+            });
+            return;
+        }
+        // Handle objects
+        if (typeof value === "object" && value !== null) {
+            const obj = value;
+            // Process each property in the object
+            for (const [key, val] of Object.entries(obj)) {
+                const fieldPath = currentPath ? `${currentPath}.${key}` : key;
+                // Try to get metadata for this field path
+                const metadata = (0, metadata_1.getFieldMetadata)(fieldPath);
+                // Add entry for this field
+                entries.push({
+                    fieldPath,
+                    value: val,
+                    metadata,
+                    hasMetadata: metadata !== undefined,
+                });
+                // Recursively process nested objects
+                if (val != null && typeof val === "object" && !Array.isArray(val)) {
+                    processValue(val, fieldPath, depth + 1);
+                }
+                else if (Array.isArray(val)) {
+                    // Process array elements
+                    processValue(val, fieldPath, depth + 1);
+                }
+            }
+        }
+    }
+    // Start processing from the root
+    if (prefix) {
+        processValue(property, prefix, 0);
+    }
+    else {
+        // Process top-level properties
+        for (const [key, value] of Object.entries(property)) {
+            const fieldPath = key;
+            const metadata = (0, metadata_1.getFieldMetadata)(fieldPath);
+            entries.push({
+                fieldPath,
+                value,
+                metadata,
+                hasMetadata: metadata !== undefined,
+            });
+            // Recursively process nested objects and arrays
+            if (value != null) {
+                processValue(value, fieldPath, 0);
+            }
+        }
+    }
+    return entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@land-catalyst/batch-data-sdk",
-  "version": "1.1.12",
+  "version": "1.1.19",
   "description": "TypeScript SDK for BatchData.io Property API - Types, Builders, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,9 @@
     "lint:fix": "eslint src --fix",
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
+    "generate:metadata": "node scripts/generate-property-field-metadata.js",
+    "generate:docs": "npx tsx scripts/generate-property-type-docs.ts",
+    "add:jsdoc": "node scripts/add-jsdoc-to-types.js",
     "v:patch": "npm version patch && git push --follow-tags",
     "v:minor": "npm version minor && git push --follow-tags",
     "v:major": "npm version major && git push --follow-tags"
@@ -34,7 +37,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/land-catalyst/batch-data-sdk.git"
+    "url": "git+https://github.com/land-catalyst/batch-data-sdk.git"
   },
   "dependencies": {
     "axios": "^1.7.9"