feat: add modifier structure

Author: ebrahimmfadae

src/permutation/definitions.ts

@@ -1,6 +1,11 @@
 export type Permutation<T = unknown> = {
 	readonly size: number;
 	readonly type: string;
+	/**
+	 * Modifiers are like meta-data that are used only by consumers
+	 * All modifiers should be idempotent
+	 */
+	readonly modifiers: string[];
 } & Iterable<T>;
 export type UnwrapPermutation<T extends Permutation> = T extends Permutation<infer U> ? U : never;
 export type PermutationGenerator<T extends Permutation = Permutation> = () => T;

src/permutation/modifiers/exports.ts

@@ -0,0 +1 @@
+export * from '#src/permutation/modifiers/optional';

src/permutation/modifiers/optional.ts

@@ -0,0 +1,21 @@
+import type {
+	Permutation,
+	PermutationGenerator,
+	UnwrapPermutation,
+} from '#src/permutation/definitions';
+
+export function optional<const T extends Permutation>(input: PermutationGenerator<T>) {
+	return function () {
+		const r = input();
+		if (r.modifiers.includes('optional')) return r;
+		return { ...r, modifiers: ['optional', ...r.modifiers] };
+	} as PermutationGenerator<
+		'optional' extends keyof T['modifiers']
+			? T
+			: Iterable<UnwrapPermutation<T>> & {
+					readonly size: T['size'];
+					readonly type: T['type'];
+					readonly modifiers: ['optional', ...T['modifiers']];
+				}
+	>;
+}

src/permutation/primitive/concat.ts

@@ -0,0 +1,31 @@
+import type {
+	Permutation,
+	PermutationGenerator,
+	UnwrapPermutation,
+} from '#src/permutation/definitions';
+import type { Sum } from '#src/utils/arithmetic/sum';
+import type { Length } from '#src/utils/common';
+
+export function concat<const T extends Permutation, const U extends unknown[]>(
+	input: PermutationGenerator<T>,
+	...values: U
+) {
+	return function () {
+		const r = input();
+		return {
+			size: (r.size + values.length) as Sum<T['size'], Length<U>>,
+			type: r.type,
+			modifiers: r.modifiers,
+			*[Symbol.iterator]() {
+				yield* r;
+				yield* values;
+			},
+		};
+	} as PermutationGenerator<
+		{
+			readonly size: Sum<T['size'], Length<U>>;
+			readonly type: T['type'];
+			readonly modifiers: T['modifiers'];
+		} & Iterable<UnwrapPermutation<T> | U[number]>
+	>;
+}

src/permutation/primitive/each.ts

@@ -6,14 +6,14 @@ export function each<const T extends readonly unknown[]>(...values: T) {
 		return {
 			size: values.length as Length<T>,
 			type: 'each',
+			modifiers: [],
 			*[Symbol.iterator]() {
 				yield* values;
 			},
 		};
 	} as PermutationGenerator<
-		{
-			readonly size: Length<T>;
-			readonly type: 'each';
-		} & Iterable<TupleToUnion<T>>
+		{ readonly size: Length<T>; readonly type: 'each'; readonly modifiers: [] } & Iterable<
+			TupleToUnion<T>
+		>
 	>;
 }

src/permutation/primitive/exports.ts

@@ -1,3 +1,2 @@
 export * from '#src/permutation/primitive/each';
-export * from '#src/permutation/primitive/optional';
 export * from '#src/permutation/primitive/record';

src/permutation/primitive/optional.ts

@@ -1,9 +1,12 @@
 import type {
+	Permutation,
 	PermutationGenerator,
 	UnwrapPermutation,
 	UnwrapPermutationGenerator,
 } from '#src/permutation/definitions';
+import { concat } from '#src/permutation/primitive/concat';
 import { explicitPermutations } from '#src/permutation/pure/explicit-permutations';
+import { REMOVE } from '#src/permutation/symbols';
 import type { PlainType } from '#src/utils/common';
 import { isExpandableArray } from '#src/utils/expandable-check';
 
@@ -19,11 +22,23 @@ export type RecordGenerator<T extends ValidRecordInput> = PlainType<{
 
 export function record<const T extends ValidRecordInput>(input: T) {
 	return function () {
-		const r = Object.entries(input).map(([k, v]) => [k, v()] as const);
-		const size = r.reduce((acc, curr) => acc * curr[1].size, 1);
+		const r = Object.entries(input).map(([k, v]) => {
+			const b = v();
+			const ret = b.modifiers.includes('optional')
+				? ([k, concat(v, REMOVE)()] as const)
+				: ([k, b] as const);
+			return ret as [string, Permutation];
+		});
+		const size = r.reduce((acc, curr) => {
+			const [, p] = curr;
+			const isOptional = p.modifiers.includes('optional');
+			const currentSize = p.size + (isOptional ? 1 : 0);
+			return acc * currentSize;
+		}, 1);
 		return {
 			size,
 			type: 'record',
+			modifiers: [],
 			*[Symbol.iterator]() {
 				if (isExpandableArray(input)) {
 					yield* explicitPermutations(r.map((v) => v[1]));
@@ -34,9 +49,8 @@ export function record<const T extends ValidRecordInput>(input: T) {
 			},
 		};
 	} as PermutationGenerator<
-		{
-			readonly size: number;
-			readonly type: 'record';
-		} & Iterable<RecordGenerator<T>>
+		{ readonly size: number; readonly type: 'record'; readonly modifiers: [] } & Iterable<
+			RecordGenerator<T>
+		>
 	>;
 }