JS Comprehension

Emulate Python-like comprehensions in JavaScript and TypeScript for more expressive and concise array transformations.

Table of Contents

• Installation
• Usage
  • Basic Comprehension
  • Multiple for Clauses
• API
  • createComprehension()
  • ComprehensionBuilder.for(iterable)
  • ComprehensionBuilder.if(conditionFn)
  • ComprehensionBuilder.select(transformFn)
• Examples
  • Nested Comprehensions with Multiple for Clauses
  • Filtering and Transforming Data
• Contributing
• License

Installation

Install via npm:

npm install js-comprehension

Usage

Basic Comprehension:

JavaScript

import { createComprehension } from 'js-comprehension';

// Generate squares of even numbers from 0 to 9
const squares = createComprehension()
  .for([...Array(10).keys()])
  .if(([x]) => x % 2 === 0)
  .select(([x]) => x ** 2);

console.log(squares); // Output: [0, 4, 16, 36, 64]

TypeScript

import { createComprehension } from 'js-comprehension';

// Generate squares of even numbers from 0 to 9 with type annotations
const squares: number[] = createComprehension<number[]>()
  .for([...Array(10).keys()] as number[])  // Type assertion for clarity
  .if(([x]: [number]) => x % 2 === 0)
  .select(([x]: [number]) => x ** 2);

console.log(squares); // Output: [0, 4, 16, 36, 64]

Multiple for Clauses:

import { createComprehension } from 'js-comprehension';

// Generate pairs where the first and second elements are not equal
const pairs = createComprehension()
  .for([0, 1, 2])
  .for([0, 1, 2])
  .if(([x, y]) => x !== y)
  .select(([x, y]) => [x, y]);

console.log(pairs);
// Output: [[0,1], [0,2], [1,0], [1,2], [2,0], [2,1]]

TypeScript

import { createComprehension } from 'js-comprehension';

// Generate pairs where the first and second elements are not equal with type annotations
const pairs: [number, number][] = createComprehension<[number, number][]>()
  .for([0, 1, 2] as number[])
  .for([0, 1, 2] as number[])
  .if(([x, y]: [number, number]) => x !== y)
  .select(([x, y]: [number, number]) => [x, y]);

console.log(pairs);
// Output: [[0,1], [0,2], [1,0], [1,2], [2,0], [2,1]]

API

createComprehension()

Creates a new instance of ComprehensionBuilder.

Returns: ComprehensionBuilder instance for chaining.

import { createComprehension } from 'js-comprehension';
const comprehension = createComprehension();

ComprehensionBuilder.for(iterable)

Specifies the iterable to loop over.

Parameters:

iterable (Iterable): An iterable object (e.g., Array, Set, etc.).

Returns: ComprehensionBuilder for chaining.

comprehension.for([1, 2, 3]);

ComprehensionBuilder.if(conditionFn)

Applies a filter condition.

Parameters:

conditionFn (Function): A function that takes an element (as a tuple) and returns a boolean.

Returns: ComprehensionBuilder for chaining.

comprehension.if(([x]) => x > 1);

ComprehensionBuilder.select(transformFn)

Transforms each element.

Parameters:

transformFn (Function): A function that takes an element and returns the transformed value.

Returns: Array of transformed elements.

const result = comprehension.select(([x]) => x * 2);

Examples

Nested Comprehensions with Multiple for Clauses

import { createComprehension } from 'js-comprehension';

const complex = createComprehension()
  .for([1, 2, 3])
  .for([4, 5])
  .if(([x, y]) => x + y > 5)
  .select(([x, y]) => x * y);

console.log(complex); // Output: [5, 8, 10, 12, 15]

TypeScript

import { createComprehension } from 'js-comprehension';

const complex: number[] = createComprehension<number[]>()
  .for([1, 2, 3] as number[])
  .for([4, 5] as number[])
  .if(([x, y]: [number, number]) => x + y > 5)
  .select(([x, y]: [number, number]) => x * y);

console.log(complex); // Output: [5, 8, 10, 12, 15]

Filtering and Transforming Data

import { createComprehension } from 'js-comprehension';

const filtered = createComprehension()
  .for([10, 15, 20, 25, 30])
  .if(([x]) => x % 10 === 0)
  .select(([x]) => `Value: ${x}`);

console.log(filtered); // Output: ["Value: 10", "Value: 20", "Value: 30"]

TypeScript

import { createComprehension } from 'js-comprehension';

const filtered: string[] = createComprehension<string[]>()
  .for([10, 15, 20, 25, 30] as number[])
  .if(([x]: [number]) => x % 10 === 0)
  .select(([x]: [number]) => `Value: ${x}`);

console.log(filtered); // Output: ["Value: 10", "Value: 20", "Value: 30"]

Contributing

Contributions are welcome! Please follow these steps:

Fork the Repository: Click the "Fork" button at the top right of the repository page.

Clone Your Fork:

git clone https://gitlab.com/3nIgm4/js-comprehension.git

Navigate to the Project Directory:

cd js-comprehension

Install Dependencies:

npm install

Create a New Branch:

git checkout -b feature/YourFeatureName

Make Your Changes: Implement your feature or bug fix.

Run Tests: Ensure all tests pass.

npm test

Commit Your Changes:

git commit -m "Add your message here"

Push to Your Fork:

git push origin feature/YourFeatureName

Open a Pull Request: Go to the original repository and click "Compare & pull request."

Reporting Issues

If you encounter any bugs or have feature requests, please open an issue.

License

MIT © Domagoj Buljan Sketchy