RozFil

Intelligent JavaScript Utility Library for Arrays and Objects

Lightweight, high-performance, and type-precise JavaScript utility library built for dataset cleaning and data exclusion across Arrays and Objects.

---

Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
• API Reference
• Supported Type Aliases
• Project Structure
• Testing
• License

---

Overview

RozFil simplifies data cleaning in JavaScript collections. Operating on an exclusion model, RozFil allows developers to target unwanted data types, exact values, or text-wrapped stringified data structures and filter them out seamlessly.

Instead of writing complex conditional loops, RozFil provides functional, depth-controlled utilities that handle edge cases (such as NaN, Infinity, null, Array vs Object, and stringified JSON) safely.

---

Key Features

• Functional Architecture: Pure logic with zero external dependencies.
• Dual Container Support: Automatically routes and filters both Arrays and Objects.
• Three-Level Type Rigor:
  • Level 1: Standard JavaScript typeof checks.
  • Level 2: Strict primitive and native type differentiation (NaN, Infinity, null, Date, Array, Object).
  • Level 3: Smart stringified type detection ('123' as number, 'true' as boolean, '[1,2]' as array, '{a:1}' as object).
• Flexible Options: Control recursion depth, in-place mutation, and case sensitivity.
• Fast Array Compaction: Implements O(N) two-pointer write compaction for high performance.

---

Installation

Clone Repository

git clone https://github.com/OmarPGH/RozFil.git
cd RozFil

Import in ES Modules

import { fbType, fbVal } from './src/index.js';

---

Quick Start

1. Filter by Type (fbType)

Exclude specific data types from an array or object:

import { fbType } from './src/index.js';

const dataset = [
  10,
  'hello',
  NaN,
  [1, 2],
  '[1, 2]',
  '123',
  undefined,
  null
];

// Exclude native numbers and stringified numbers (rigor level 3)
const cleaned = fbType(dataset, ['num'], { rigor: 3 });
// Result: ['hello', NaN, [], '[1, 2]', undefined, null]

// Strict exclusion of NaN and Arrays (rigor level 2)
const strictClean = fbType(dataset, ['nan', 'arr'], { rigor: 2 });
// Result: [10, 'hello', '[1, 2]', '123', undefined, null]

2. Filter by Value (fbVal)

Exclude specific values from an array or nested object:

import { fbVal } from './src/index.js';

const userData = {
  user1: { name: 'Omar', role: 'Admin' },
  user2: { name: 'Yuna', role: 'Guest' },
  user3: { name: 'Harry', role: 'admin' }
};

// Case-insensitive exclusion of 'admin' values across depth 2
const activeUsers = fbVal(userData, ['admin'], { cs: false, depth: 2 });
// Result removes matching property values regardless of casing

---

API Reference

fbType(data, types, options)

Excludes items from data based on type specifications.

• data (Array | Object): Target collection to filter.
• types (Array | string): Type names or shorthand aliases to exclude.
• options (Object): Configuration settings:
  • rigor (number): Type detection precision level (1, 2, or 3). Default: 1.
  • depth (number): Traversal depth limit for nested structures. Default: Infinity.
  • inPlace (boolean): Mutates the original object/array if true. Default: false.

fbVal(data, values, options)

Excludes items from data that match specific values.

• data (Array | Object): Target collection to filter.
• values (Array | any): Values to match and remove.
• options (Object): Configuration settings:
  • cs (boolean): Case sensitivity flag for string comparisons. Default: true.
  • depth (number): Traversal depth limit for nested structures. Default: Infinity.
  • inPlace (boolean): Mutates the original object/array if true. Default: false.

---

Supported Type Aliases

RozFil supports shorthand type aliases for fast and clean filtering:

Shorthand	Canonical Name	Description
str	string	String primitives
num	number	Numeric values
bln	boolean	Boolean values (true / false)
uf	undefined	Undefined values
fun	function	Functions
nl	null	Null values
arr	array	Native Arrays
obj	object	Plain Objects
nan	NaN	Not-a-Number values
bi	bigint	BigInt primitives
ifty	Infinity	Infinity numerical values
smbl	symbol	Symbol primitives
tru	true	Boolean true
fls	false	Boolean false
emptystr	emptyString	Empty strings ("")
ss	emptyStringWithSpaces	Whitespace-only strings
ss?	emptyStringOrWithSpaces	Empty or whitespace strings
{s?}	emptyObject	Empty objects ({})
[s?]	emptyArray	Empty arrays ([])
date	date	Parseable date strings

---

Project Structure

Generated by Raqule

RozFil
├── .git
├── .github
│   └── workflows
│       └── semgrep.yml
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── package.json
├── src
│   ├── core
│   │   ├── baseFilterEngine.js
│   │   └── index.js
│   ├── engines
│   │   ├── arrayFilterEngine.js
│   │   ├── index.js
│   │   └── objectFilterEngine.js
│   ├── filters
│   │   ├── filterByType.js
│   │   └── filterByValue.js
│   ├── helpers
│   │   ├── filterEngineRouter.js
│   │   ├── index.js
│   │   ├── invalid.js
│   │   ├── isWalkable.js
│   │   ├── jsonValidator.js
│   │   ├── regexValidator.js
│   │   └── translator.js
│   └── index.js
└── tests
    ├── arr.js
    └── obj.js

---

Testing

Run test execution scripts using Node.js:

# to run [ test/unit & test/integration ] test files.
npm test

# to run [ test/unit & test/integration ] test files but in watch mode.
npm run test:watch

# to run test/stress test files.
npm run test:stress

---

License

This project is licensed under the Apache-2.0. See the LICENSE file for details.

---

Author

Omar Gamal - Creator and Maintainer