@medyll/idae-engine 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# @medyll/engine
+
+A powerful TypeScript library for data manipulation and operations across the idae-engine.
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install @medyll/idae-engine
+```
+
+Or using yarn:
+
+```bash
+yarn add @medyll/idae-engine
+```
+
+## Usage
+
+The `@medyll/idae-eengine` package contains several utility classes. This section focuses on the `dataOp` class, which provides various data manipulation methods.
+
+### Importing
+
+```typescript
+import { dataOp } from '@medyll/idae-engine';
+```
+## dataOp
+### Methods
+
+#### do
+
+Performs a combination of sort, find, and group operations on data.
+
+```typescript
+const result = dataOp.do({
+  sort: { arr: myArray, by: 'fieldName', sort: 'asc' },
+  find: { arr: myArray, kw: 'searchTerm', field: 'fieldName' },
+  group: { dataList: myArray, groupBy: 'fieldName' }
+});
+```
+
+#### sortBy
+
+Sorts an array of objects based on specified fields.
+
+```typescript
+const sortedArray = dataOp.sortBy({
+  arr: myArray,
+  by: 'fieldName',
+  sort: 'asc'
+});
+```
+
+#### find
+
+Searches for objects in an array based on specified criteria.
+
+```typescript
+const foundItems = dataOp.find({
+  arr: myArray,
+  kw: 'searchTerm',
+  field: 'fieldName'
+});
+```
+
+#### findOne
+
+Searches for the first object in an array that matches the specified criteria.
+
+```typescript
+const foundItem = dataOp.findOne({
+  arr: myArray,
+  kw: 'searchTerm',
+  field: 'fieldName'
+});
+```
+
+#### groupBy
+
+Groups objects in an array based on specified fields or a custom grouping function.
+
+```typescript
+const groupedData = dataOp.groupBy({
+  dataList: myArray,
+  groupBy: 'fieldName'
+});
+```
+
+#### findByIndex
+
+Finds the index of an object in an array based on a specified key-value pair.
+
+```typescript
+const index = dataOp.findByIndex(myArray, 'value', 'keyName');
+```
+
+#### resolveDotPath
+
+Resolves a dot-notated path in an object.
+
+```typescript
+const value = dataOp.resolveDotPath(myObject, 'path.to.property');
+```
+
+### Testing
+
+The `dataOp` class comes with a comprehensive test suite. To run the tests:
+
+1. Clone the repository
+2. Install dependencies: `npm install` or `yarn install`
+3. Run tests: `npm test` or `yarn test`
+
+The tests cover various scenarios for each method, ensuring the reliability and correctness of the `dataOp` class.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License.

package/dist/dataOp/dataOp.d.ts

@@ -0,0 +1,122 @@
+import { type ResolverPathType } from "./types.js";
+type Data = Record<string, any>;
+export type DataGroupResult<T> = {
+    [key: string]: {
+        title: string;
+        code?: string;
+        data: T[];
+    };
+};
+type DataSortBy<T> = {
+    arr: T[];
+    by: Partial<Record<ResolverPathType<T>, "asc" | "desc" | 1 | -1 | undefined>>;
+    options?: {
+        keepRef: true;
+    };
+} | {
+    arr: T[];
+    by: ResolverPathType<T> | ResolverPathType<T>[];
+    sort?: "asc" | "desc" | 1 | -1 | undefined;
+    options?: {
+        keepRef: true;
+    };
+};
+type DataFind<T> = {
+    kw: number | string;
+    arr: T[];
+    field?: ResolverPathType<T> | "*";
+    caseSensitive?: boolean;
+    strict?: false;
+};
+type DataGroupBy<T> = {
+    dataList: T[];
+    groupBy: ((item: T) => {
+        title: string;
+        code: string;
+    }) | ResolverPathType<T> | ResolverPathType<T>[];
+    keepUngroupedData?: boolean;
+};
+/** data manipulation class */
+export declare class dataOp {
+    /**
+     * Performs a combination of sort, find, and group operations on data.
+     *
+     * @template T - The type of objects in the array, extends Data.
+     * @param {Object} options - The options for data operations.
+     * @param {DataSortBy<T>} [options.sort] - Sorting options.
+     * @param {DataFind<T>} [options.find] - Finding options.
+     * @param {DataGroupBy<T>} [options.group] - Grouping options.
+     * @returns {T[] | GroupResult<T>} The resulting array or grouped data.
+     */
+    static do<T extends Data>(options: {
+        sort?: DataSortBy<T>;
+        find?: DataFind<T>;
+        group?: DataGroupBy<T>;
+    }): T[] | DataGroupResult<T>;
+    /**
+     * Sorts an array of objects based on one or more specified fields with individual sort directions.
+     *
+     * @template T - The type of objects in the array, extends Data.
+     * @param {DataSortBy<T>} sortOptions - The sorting options.
+     * @returns {T[]} The sorted array.
+     */
+    static sortBy<T extends Data>(sortOptions: DataSortBy<T>): T[];
+    /**
+     * Searches for objects in an array based on specified criteria.
+     *
+     * @template T - The type of objects in the array, defaults to Record<string, unknown>.
+     * @param {Object} options - The search options.
+     * @param {number|string} options.kw - The keyword to search for.
+     * @param {T[]} options.in - The array to search in.
+     * @param {(keyof T | ResolverPathType<T> | "*")} [options.field="*"] - The field to search in. Use "*" to search in all fields.
+     * @param {boolean} [options.caseSensitive=false] - Whether the search should be case-sensitive.
+     * @returns {T[]} An array of objects that match the search criteria.
+     */
+    static find<T extends object = Record<string, unknown>>(options: DataFind<T>): T[];
+    /**
+     * Searches for the first object in an array that matches the specified criteria.
+     *
+     * @template T - The type of objects in the array, defaults to Record<string, unknown>.
+     * @param {Object} options - The search options.
+     * @param {T[]} options.arr - The array to search in.
+     * @param {number|string} options.kw - The keyword to search for.
+     * @param {(ResolverPathType<T> | "*")} [options.field="*"] - The field to search in. Use "*" to search in all fields.
+     * @param {boolean} [options.caseSensitive=false] - Whether the search should be case-sensitive.
+     * @returns {T | undefined} The first object that matches the search criteria, or undefined if no match is found.
+     */
+    static findOne<T extends Data>(options: DataFind<T>): T | undefined;
+    /**
+     * Groups objects in an array based on specified fields or a custom grouping function.
+     *
+     * @template T - The type of objects in the array, defaults to Data.
+     * @param {Object} options - The grouping options.
+     * @param {T[]} options.dataList - The array to group.
+     * @param {((item: T) => { title: string; code: string }) | ResolverPathType<T> | ResolverPathType<T>[]} options.groupBy - The field(s) to group by or a function to determine the group.
+     * @param {boolean} [options.keepUngroupedData=false] - Whether to keep ungrouped data.
+     * @returns {DataGroupResult<T>} An object where keys are group codes and values are objects containing title, code, and data array.
+     */
+    static groupBy<T = Data>(options: DataGroupBy<T>): DataGroupResult<T>;
+    /**
+     *
+     * @param arr array to find in
+     * @param value value to seek for
+     * @param key  object key to match with
+     * @returns number
+     */
+    static findByIndex<T = Record<string, any>>(arr: T[], value: any, key?: keyof T | ResolverPathType<T>): number;
+    static resolveDotPath<T = Data>(object: T, path: ResolverPathType<T>, defaultValue?: any): any;
+    /**
+     * Compares two values for sorting.
+     *
+     * @private
+     * @template T - The type of objects being compared.
+     * @param {T} a - The first object to compare.
+     * @param {T} b - The second object to compare.
+     * @param {ResolverPathType<T>} field - The field to compare.
+     * @param {number} sortD - The sort direction (1 for ascending, -1 for descending).
+     * @returns {number} The comparison result.
+     */
+    private static compareValues;
+    private static compareSearchValues;
+}
+export {};

package/dist/dataOp/dataOp.js

@@ -0,0 +1,195 @@
+import {} from "./types.js";
+/** data manipulation class */
+export class dataOp {
+    /**
+     * Performs a combination of sort, find, and group operations on data.
+     *
+     * @template T - The type of objects in the array, extends Data.
+     * @param {Object} options - The options for data operations.
+     * @param {DataSortBy<T>} [options.sort] - Sorting options.
+     * @param {DataFind<T>} [options.find] - Finding options.
+     * @param {DataGroupBy<T>} [options.group] - Grouping options.
+     * @returns {T[] | GroupResult<T>} The resulting array or grouped data.
+     */
+    static do(options) {
+        let result = options.sort?.arr || options.find?.arr || options.group?.dataList || [];
+        if (options.sort) {
+            result = this.sortBy(options.sort);
+        }
+        if (options.find) {
+            result = this.find({ ...options.find, arr: result });
+        }
+        if (options.group) {
+            return this.groupBy({ ...options.group, dataList: result });
+        }
+        return result;
+    }
+    /**
+     * Sorts an array of objects based on one or more specified fields with individual sort directions.
+     *
+     * @template T - The type of objects in the array, extends Data.
+     * @param {DataSortBy<T>} sortOptions - The sorting options.
+     * @returns {T[]} The sorted array.
+     */
+    static sortBy(sortOptions) {
+        const { arr, options } = sortOptions;
+        const sortArray = options?.keepRef ? arr : [...arr];
+        if (!sortOptions.by ||
+            (Array.isArray(sortOptions.by) && sortOptions.by.length === 0)) {
+            return sortArray;
+        }
+        return sortArray.sort((a, b) => {
+            if ("sort" in sortOptions) {
+                const { by, sort = "asc" } = sortOptions;
+                const sortD = sort === "asc" || sort === 1 ? 1 : -1;
+                const fields = Array.isArray(by) ? by : [by];
+                for (const field of fields) {
+                    const comparison = this.compareValues(a, b, field, sortD);
+                    if (comparison !== 0)
+                        return comparison;
+                }
+            }
+            else {
+                for (const [field, direction] of Object.entries(sortOptions.by)) {
+                    const sortD = direction === "asc" || Number(direction) === 1 ? 1 : -1;
+                    const comparison = this.compareValues(a, b, field, sortD);
+                    if (comparison !== 0)
+                        return comparison;
+                }
+            }
+            return 0;
+        });
+    }
+    /**
+     * Searches for objects in an array based on specified criteria.
+     *
+     * @template T - The type of objects in the array, defaults to Record<string, unknown>.
+     * @param {Object} options - The search options.
+     * @param {number|string} options.kw - The keyword to search for.
+     * @param {T[]} options.in - The array to search in.
+     * @param {(keyof T | ResolverPathType<T> | "*")} [options.field="*"] - The field to search in. Use "*" to search in all fields.
+     * @param {boolean} [options.caseSensitive=false] - Whether the search should be case-sensitive.
+     * @returns {T[]} An array of objects that match the search criteria.
+     */
+    static find(options) {
+        const { arr, kw, field = "*", caseSensitive = false, strict = false, } = options;
+        return arr.filter((item) => {
+            if (field !== "*") {
+                const itemValue = this.resolveDotPath(item, field);
+                return this.compareSearchValues(itemValue, kw, caseSensitive, strict);
+            }
+            return Object.values(item).some((value) => this.compareSearchValues(value, kw, caseSensitive, strict));
+        });
+    }
+    /**
+     * Searches for the first object in an array that matches the specified criteria.
+     *
+     * @template T - The type of objects in the array, defaults to Record<string, unknown>.
+     * @param {Object} options - The search options.
+     * @param {T[]} options.arr - The array to search in.
+     * @param {number|string} options.kw - The keyword to search for.
+     * @param {(ResolverPathType<T> | "*")} [options.field="*"] - The field to search in. Use "*" to search in all fields.
+     * @param {boolean} [options.caseSensitive=false] - Whether the search should be case-sensitive.
+     * @returns {T | undefined} The first object that matches the search criteria, or undefined if no match is found.
+     */
+    static findOne(options) {
+        const { arr, kw, field = "*", caseSensitive = false, strict = false, } = options;
+        return arr.find((item) => {
+            if (field !== "*") {
+                const itemValue = this.resolveDotPath(item, field);
+                return this.compareSearchValues(itemValue, kw, caseSensitive, strict);
+            }
+            return Object.values(item).some((value) => this.compareSearchValues(value, kw, caseSensitive, strict));
+        });
+    }
+    /**
+     * Groups objects in an array based on specified fields or a custom grouping function.
+     *
+     * @template T - The type of objects in the array, defaults to Data.
+     * @param {Object} options - The grouping options.
+     * @param {T[]} options.dataList - The array to group.
+     * @param {((item: T) => { title: string; code: string }) | ResolverPathType<T> | ResolverPathType<T>[]} options.groupBy - The field(s) to group by or a function to determine the group.
+     * @param {boolean} [options.keepUngroupedData=false] - Whether to keep ungrouped data.
+     * @returns {DataGroupResult<T>} An object where keys are group codes and values are objects containing title, code, and data array.
+     */
+    static groupBy(options) {
+        const { dataList, groupBy: groupField, keepUngroupedData = false, } = options;
+        return dataList.reduce((result, currentItem) => {
+            let groupInfo;
+            if (typeof groupField === "function") {
+                groupInfo = groupField(currentItem);
+            }
+            else {
+                const fields = Array.isArray(groupField) ? groupField : [groupField];
+                const groupValue = fields
+                    .map((field) => this.resolveDotPath(currentItem, field))
+                    .filter((value) => value !== undefined)
+                    .join(".");
+                if (groupValue) {
+                    groupInfo = { title: groupValue, code: groupValue };
+                }
+            }
+            if (!groupInfo) {
+                if (!keepUngroupedData)
+                    return result;
+                groupInfo = { title: "- Ungrouped", code: "- ungrouped" };
+            }
+            const groupKey = groupInfo.code;
+            if (!result[groupKey]) {
+                result[groupKey] = {
+                    title: groupInfo.title,
+                    code: groupInfo.code,
+                    data: [],
+                };
+            }
+            result[groupKey].data.push(currentItem);
+            return result;
+        }, {});
+    }
+    /**
+     *
+     * @param arr array to find in
+     * @param value value to seek for
+     * @param key  object key to match with
+     * @returns number
+     */
+    static findByIndex(arr, value, key = "id") {
+        return arr.findIndex((obj) => this.resolveDotPath(obj, key) === value);
+    }
+    static resolveDotPath(object, path, defaultValue) {
+        return path
+            .split(".")
+            .reduce((r, s) => (r && typeof r === "object" && s in r ? r[s] : defaultValue), object);
+    }
+    /**
+     * Compares two values for sorting.
+     *
+     * @private
+     * @template T - The type of objects being compared.
+     * @param {T} a - The first object to compare.
+     * @param {T} b - The second object to compare.
+     * @param {ResolverPathType<T>} field - The field to compare.
+     * @param {number} sortD - The sort direction (1 for ascending, -1 for descending).
+     * @returns {number} The comparison result.
+     */
+    static compareValues(a, b, field, sortD) {
+        const aValue = this.resolveDotPath(a, field);
+        const bValue = this.resolveDotPath(b, field);
+        if (typeof aValue === "string" && typeof bValue === "string") {
+            return sortD * aValue.localeCompare(bValue);
+        }
+        return sortD * (aValue > bValue ? 1 : aValue < bValue ? -1 : 0);
+    }
+    static compareSearchValues(itemValue, searchValue, caseSensitive, strict) {
+        const strItemValue = String(itemValue);
+        const strSearchValue = String(searchValue);
+        if (strict) {
+            return caseSensitive
+                ? strItemValue === strSearchValue
+                : strItemValue.toLowerCase() === strSearchValue.toLowerCase();
+        }
+        return caseSensitive
+            ? strItemValue.includes(strSearchValue)
+            : strItemValue.toLowerCase().includes(strSearchValue.toLowerCase());
+    }
+}

package/dist/dataOp/types.d.ts

@@ -0,0 +1,3 @@
+export type ResolverPathType<T> = T extends object ? {
+    [K in keyof T]: (K & string) | (T[K] extends object ? `${K & string}.${ResolverPathType<T[K]>}` : never);
+}[keyof T] : never;

package/dist/dataOp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dataOp/dataOp.js';
+export * from './dataOp/types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+// Reexport of entry components
+export * from './dataOp/dataOp.js';
+export * from './dataOp/types.js';

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@medyll/idae-engine",
+	"scope": "@medyll",
+	"version": "1.0.0",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run package",
+		"preview": "vite preview",
+		"package": "svelte-kit sync && svelte-package && publint",
+		"package:watch": "svelte-kit sync && svelte-package --watch",
+		"prepublishOnly": "npm run package",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"test": "vitest"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"peerDependencies": {
+		"svelte": "^4.0.0"
+	},
+	"devDependencies": {
+		"@sveltejs/adapter-auto": "^3.0.0",
+		"@sveltejs/kit": "^2.0.0",
+		"@sveltejs/package": "^2.0.0",
+		"@sveltejs/vite-plugin-svelte": "^3.0.0",
+		"publint": "^0.1.9",
+		"svelte": "^5.0.0-next.183",
+		"svelte-check": "^3.6.0",
+		"tslib": "^2.4.1",
+		"typescript": "^5.0.0",
+		"vite": "^5.0.11",
+		"vitest": "^1.2.0"
+	},
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module"
+}