unicorefw 1.1.2
Universal Core Utility Library
Requires Python: >=3.7

<p align="center"><img src="https://unicorefw.org/img/logo.png?v=1.0.2" /></p>
        
        |                        | Arrays | Objects | Functions | Utilities |
        | :--------------------- | -----: | ------: | --------: | --------: |
        | **Test Status**  |     ✓ |      ✓ |        ✓ |        ✓ |
        | **Build Status** |     ✓ |      ✓ |        ✓ |        ✓ |
        
        [![Publish to PyPi](https://github.com/unicorefw-org/unicorefw-py/actions/workflows/release.yml/badge.svg)](https://pypistats.org/packages/unicorefw) [![Unit Tests](https://github.com/unicorefw-org/unicorefw-py/actions/workflows/tests.yml/badge.svg)](https://github.com/unicorefw-org/unicorefw-py/actions/workflows/tests.yml)
        
        # UniCoreFW
        
        [![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE) [![Python Version](https://img.shields.io/badge/python-3.6%2B-blue)](https://www.python.org/downloads/)
        
        **Universal Core Utility Library**
        
        UniCoreFW is a comprehensive utility library that provides a wide range of functions for arrays, objects, functions, and more, all with a focus on universality, security, and performance.
        
        ## Features
        
        - **Security-First Design**: Built-in input validation, rate limiting, and audit logging
        - **Functional Programming**: Map, reduce, filter, and other higher-order functions
        - **Chainable API**: Similar to libraries like Lodash/Underscore
        - **Comprehensive Toolset**: 100+ utility functions organized into logical categories
        - **Type Checking**: Extensive type checking and validation utilities
        
        Changelogs
        ----------
        
        Please visit: [Releases](https://github.com/unicorefw-org/unicorefw-py/releases)
        
        
        ## Installation from Pypi using PIP
        
        ```bash
        pip install unicorefw
        ```
        
        Installation from source
        ------------------------
        
        1. Clone the repository:
        
        ```bash
        git clone https://github.com/unicorefw-org/unicorefw-py.git
           cd unicorefw-py
        ```
        
        2. Ensure Python 3.x is installed on your system.
        3. Directory Structure
        
        ```
        project_root_dir/
        ├── unicorefw/
        │   └── __init__
        │   └── array.py
        │   └── core.py
        │   └── function.py
        │   └── object.py
        │   └── security.py
        │   └── template.py
        │   └── types.py
        │   └── utils.py
        ├── examples/
        │   └── sets/            # List of examples
        │   └── functions.py     # Show examples of function usage
        │   └── task_manager.py  # Sample implementations using UniCoreFW functions
        │   └── underscore.py    # Examples on how to use UniCoreFW as _
        └── README.md
        ```
        
        ## Quick Start
        
        ```python
        from unicorefw import _, UniCoreFW, UniCoreFWWrapper
        
        # Chaining example
        result = (_([1, 2, 3, 4, 5])
                    .map(lambda x: x * 2)
                    .filter(lambda x: x > 5)
                    .value())
                  
        print(f"Chained result: {result}")  # Output: [6, 8, 10]
        
        # Static method example
        template = "Name: <%= name %>, Age: <%= age %>"
        context = {"name": "Alice", "age": 25}
        print(f"Template result: {_.template(template, context)}")  
        # Output: "Name: Alice, Age: 25"
        
        # Multiple operations example
        data = [
            {"name": "Alice", "age": 25, "active": True},
            {"name": "Bob", "age": 30, "active": False},
            {"name": "Charlie", "age": 35, "active": True}
        ]
        
        active_names = (_(data)
                        .filter(lambda x: x.get("active", False))
                        .pluck("name")
                        .value())
        print(f"Active users: {active_names}")  # Output: ['Alice', 'Charlie']
        
        # Demonstrate static vs chained methods
        array = [1, 2, 3, 4, 5]
        print(f"Static map: {_.map(array, lambda x: x * 3)}")
        print(f"Chained map: {_(array).map(lambda x: x * 3).value()}")
        ```
        
        ## Core Modules
        
        ### Array Functions
        
        ```python
        # Map, filter, reduce
        mapped = UniCoreFW.map([1, 2, 3], lambda x: x * 2)  # [2, 4, 6]
        filtered = UniCoreFW.filter([1, 2, 3, 4], lambda x: x % 2 == 0)  # [2, 4]
        reduced = UniCoreFW.reduce([1, 2, 3, 4], lambda a, b: a + b, 0)  # 10
        
        # Array manipulation
        first = UniCoreFW.first([1, 2, 3], n=2)  # [1, 2]
        last = UniCoreFW.last([1, 2, 3], n=2)  # [2, 3]
        flattened = UniCoreFW.flatten([1, [2, [3, 4]]])  # [1, 2, 3, 4]
        chunked = UniCoreFW.chunk([1, 2, 3, 4, 5, 6], 2)  # [[1, 2], [3, 4], [5, 6]]
        ```
        
        ### Object Functions
        
        ```python
        # Object manipulation
        keys = UniCoreFW.keys({"a": 1, "b": 2})  # ["a", "b"]
        values = UniCoreFW.values({"a": 1, "b": 2})  # [1, 2]
        extended = UniCoreFW.extend({"a": 1}, {"b": 2}, {"c": 3})  # {"a": 1, "b": 2, "c": 3}
        
        # Object creation
        obj = UniCoreFW.object(["a", "b"], [1, 2])  # {"a": 1, "b": 2}
        ```
        
        ### Function Utilities
        
        ```python
        # Function transformation
        def add(a, b):
            return a + b
        
        add_5 = UniCoreFW.partial(add, 5)  # Creates a new function that adds 5
        result = add_5(10)  # 15
        
        # Execution control
        throttled = UniCoreFW.throttle(expensive_function, 1000)  # Max once per second
        debounced = UniCoreFW.debounce(on_input_change, 300)  # Wait for 300ms of inactivity
        memoized = UniCoreFW.memoize(fibonacci)  # Cache results for repeated calls
        ```
        
        ### Security Utilities
        
        ```python
        from unicorefw import validate_type, validate_callable, sanitize_string
        
        # Input validation
        validate_type("test", str, "string_param")
        validate_callable(lambda x: x, "function_param")
        
        # String sanitization
        safe_input = sanitize_string(user_input, max_length=100, allowed_chars="a-zA-Z0-9")
        
        # Rate limiting
        with RateLimiter(max_calls=100, time_window=60):
            perform_api_request()
        
        # Audit logging
        logger = AuditLogger(log_file="security.log")
        logger.log("LOGIN", "User authenticated successfully")
        ```
        
        ### Special Algorithms
        
        ```python
        # Find median of two sorted arrays
        median = UniCoreFW.find_median_sorted_arrays([1, 3, 5], [2, 4, 6])  # 3.5
        
        # String compression
        compressed = UniCoreFW.compress("aaabbc")  # "3a2b1c"
        decompressed = UniCoreFW.decompress("3a2b3c")  # "aaabbccc"
        ```
        
        ## Advanced Examples
        
        ### Data Processing Pipeline
        
        ```python
        def process_data(items):
            return (_(items)
                    .filter(lambda x: x["active"])
                    .sort_by(lambda x: x["priority"])
                    .map(lambda x: {
                        "id": x["id"],
                        "status": "High" if x["priority"] > 5 else "Low"
                    })
                    .value())
        
        result = process_data([
            {"id": 1, "active": True, "priority": 7},
            {"id": 2, "active": False, "priority": 3},
            {"id": 3, "active": True, "priority": 4}
        ])
        # [{"id": 3, "status": "Low"}, {"id": 1, "status": "High"}]
        ```
        
        ### Secure Template Rendering
        
        ```python
        template = "Hello, <%= name %>! Your role is: <%= role %>."
        context = {"name": "John", "role": "Admin"}
        
        rendered = UniCoreFW.template(template, context)
        # "Hello, John! Your role is: Admin."
        ```
        
        **PYTHON IMPLEMENTATION**
        ---------------------
        
        # Architecture
        
        **UniCoreFW**	 is Primary class that providing static utility methods	like UniCoreFW.method_name(arguments)
        
        **UniCoreFWWrapper** is Wrapper class that enables method chaining like UniCoreFWWrapper(collection).method1().method2().value()
        
        This class, `UniCoreFW`, provides a wide range of utility functions for working with arrays, objects, and strings. Here's a summary of what each method does:
        
        **Array Functions**
        
        - `_.map` – Transforms an array's elements based on a function.
        - `_.reduce` – Reduces an array to a single value using a function.
        - `_.reduce_right` – Like - `_.reduce, but starts from the right.
        - `_.find` – Returns the first value that matches a predicate.
        - `_.filter` – Returns an array of values that match a predicate.
        - `_.where` – Filters an array of objects, matching a set of key-value pairs.
        - `_.find_where` – Like - `_.where, but returns only the first match.
        - `_.reject` – Returns an array of values that fail a predicate.
        - `_.every` – Tests whether all values pass a predicate.
        - `_.some` – Tests whether any values pass a predicate.
        - `_.contains` – Checks if a value exists in an array.
        - `_.invoke` – Invokes a method on every item in a collection.
        - `_.pluck` – Extracts a list of values from an array of objects.
        - `_.max` – Returns the maximum value based on a function.
        - `_.min` – Returns the minimum value based on a function.
        - `_.sort_by` – Sorts an array by a function's result.
        - `_.group_by` – Groups an array by the result of a function.
        - `_.index_by` – Indexes an array by a property value or function result.
        - `_.count_by` – Counts instances of values by a function's result.
        - `_.shuffle` – Shuffles the values in an array.
        - `_.sample` – Selects random values from an array.
        - `_.to_array` – Converts an iterable into an array.
        - `_.size` – Returns the size of a collection.
        - `_.partition` – Splits a collection into two arrays based on a predicate.
        - `_.first` – Returns the first elements of an array.
        - `_.initial` – Returns everything but the last element of an array.
        - `_.last` – Returns the last elements of an array.
        - `_.rest` – Returns everything but the first element of an array.
        - `_.compact` – Removes falsey values from an array.
        - `_.flatten` – Flattens a nested array.
        - `_.without` – Returns an array with specified values removed.
        - `_.uniq` – Removes duplicate values from an array.
        - `_.union` – Combines arrays, removing duplicates.
        - `_.intersection` – Returns values common to all arrays.
        - `_.difference` – Returns values from the first array not present in others.
        - `_.zip` – Merges arrays based on their index.
        - `_.unzip` – Reverses the process of - `_.zip.
        - `_.object` – Converts an array of pairs into an object.
        - `_.range` – Creates an array of numbers in a range.
        - `_.chunk` – Splits an array into chunks of a specified size.
        
        **Object Functions**
        
        - `_.keys` – Returns an array of an object's keys.
        - `_.all_keys` – Returns an array of an object's keys, including inherited ones.
        - `_.values` – Returns an array of an object's values.
        - `_.map_object` – Applies a function to each value of an object.
        - `_.pairs` – Converts an object into an array of [key, value] pairs.
        - `_.invert` – Inverts an object's keys and values.
        - `_.functions` – Returns an array of all function property names in an object.
        - `_.extend` – Extends an object with the properties of other objects.
        - `_.extend_own` – Like - `_.extend, but only copies own properties.
        - `_.defaults` – Assigns default properties to an object.
        - `_.create` – Creates an object with a specified prototype.
        - `_.clone` – Creates a shallow copy of an object.
        - `_.tap` – Invokes a function with an object and returns the object.
        - `_.has` – Checks if an object contains a given property.
        - `_.property` – Returns a function that retrieves a property value.
        - `_.property_of` – Returns a function that retrieves a property value from a given object.
        - `_.matcher (or - `_.matches)` – Creates a function that checks for matching key-value pairs.
        - `_.is_equal` – Performs a deep comparison between objects.
        - `_.is_match` – Checks if an object matches key-value pairs.
        - `_.is_empty` – Checks if an object is empty.
        - `_.is_element` – Checks if an object is a DOM element.
        - `_.is_array` – Checks if a value is an array.
        - `_.is_object` – Checks if a value is an object.
        - `_.is_arguments` – Checks if a value is an arguments object.
        - `_.is_function` – Checks if a value is a function.
        - `_.is_string` – Checks if a value is a string.
        - `_.is_number` – Checks if a value is a number.
        - `_.is_finite` – Checks if a value is a finite number.
        - `_.is_boolean` – Checks if a value is a boolean.
        - `_.is_date` – Checks if a value is a date.
        - `_.is_reg_exp` – Checks if a value is a regular expression.
        - `_.is_error` – Checks if a value is an error.
        - `_.is_symbol` – Checks if a value is a symbol.
        - `_.is_map` – Checks if a value is a map.
        - `_.is_weak_map` – Checks if a value is a weak map.
        - `_.is_set` – Checks if a value is a set.
        - `_.is_weak_set` – Checks if a value is a weak set.
        - `_.is_null` – Checks if a value is null.
        - `_.is_undefined` – Checks if a value is undefined.
        - `_.is_nan` – Checks if a value is NaN.
        - `_.is_typed_array` – Checks if a value is a typed array.
        - `_.is_array_buffer` – Checks if a value is an array buffer.
        - `_.is_data_view` – Checks if a value is a data view.
        
        **Utility Functions**
        
        - `_.identity` – Returns the same value that is passed.
        - `_.constant` – Returns a function that returns the given value.
        - `_.noop` – A function that does nothing.
        - `_.times` – Invokes a function a specified number of times.
        - `_.random` – Returns a random number between a min and max.
        - `_.mixin` – Adds functions to the Underscore object.
        - `_.iteratee` – Returns a function that can be applied to each element in a collection.
        - `_.unique_id` – Generates a unique identifier.
        - `_.escape` – Escapes a string for inclusion in HTML.
        - `_.unescape` – Unescapes a string from HTML.
        - `_.result` – Resolves the value of a property, potentially invoking it as a function.
        - `_.now` – Returns the current timestamp.
        - `_.template` – Compiles a template to a function.
        - `_.chain` – Returns a wrapped object to allow chaining of functions.
        - `_.value` – Extracts the result from a chained object.
        
        **Function Functions**
        
        - `_.bind` – Binds a function to an object.
        - `_.partial` – Partially applies a function by pre-filling some arguments.
        - `_.bind_all` – Binds methods of an object to the object itself.
        - `_.memoize` – Caches the result of a function call.
        - `_.delay` – Delays a function for a specified number of milliseconds.
        - `_.defer` – Defers a function to be executed after the current call stack clears.
        - `_.throttle` – Creates a throttled version of a function.
        - `_.debounce` – Creates a debounced version of a function.
        - `_.once` – Ensures a function is only called once.
        - `_.after` – Returns a function that will only run after it has been called N times.
        - `_.before` – Returns a function that will run until it has been called N times.
        - `_.wrap` – Wraps a function inside another function.
        - `_.negate` – Returns the negation of a predicate function.
        - `_.compose` – Composes functions together to run in sequence.
        
        **Chaining Functions**
        
        - `_.chain` – Starts a chain.
        - `_.value` – Extracts the value at the end of a chain.
        
        ## Why UniCoreFW?
        
        ### Universality
        
        UniCoreFW provides consistent APIs across different environments and use cases, allowing you to write cleaner, more maintainable code.
        
        ### Security
        
        Every function is designed with security in mind, including input validation, rate limiting, and audit logging capabilities.
        
        ### Performance
        
        Functions are optimized for minimal overhead, suitable for both small applications and enterprise-level systems.
        
        ## License
        
        This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
        
        ## Contributing
        
        Contributions are welcome! Please feel free to submit a Pull Request.
        
        ## Authors
        
        - **Kenny Ngo** - *Initial work* - [UniCoreFW.Org](https://unicorefw.org) / [IIPTech.info](https://iiptech.info)