chore: improved interface and README

Author: lmammino

README.md

@@ -21,20 +21,43 @@ npm install indexed-string-variation
 
 ## Usage
 
-This library is ESM-only and written in TypeScript. You can import it as
+This library is ESM-only and written in TypeScript. You can import and use it as
 follows:
 
 ```js
-import { generator } from "indexed-string-variation";
+import isv from "indexed-string-variation";
 
-const variations = generator("abc1");
+// Basic usage: generate all variations for a given alphabet
+for (
+  const str of isv({ alphabet: "abc1", maxIterations: 23 })
+) {
+  console.log(str);
+}
+
+// Generate variations from a specific index (using BigInt)
+for (
+  const str of isv({
+    alphabet: "abc1",
+    from: 20n,
+    maxIterations: 5,
+  })
+) {
+  console.log(str);
+}
 
-for (let i = 0; i < 23; i++) {
-  console.log(i, variations(i)); // generates the i-th string in the alphabet 'abc1'
+// Generate variations up to a maximum string length
+for (const str of isv({ alphabet: "abc1", maxLen: 2 })) {
+  console.log(str);
 }
 
-// Using BigInt for large indices
-console.log(variations(12345678901234567890n));
+// endless variations (don't use a `for ... of` loop because it will never end!)
+const values = isv({
+  alphabet: "abc1",
+});
+
+console.log(values.next()); // { value: 'a', done: false }
+console.log(values.next()); // { value: 'b', done: false }
+//...
 ```
 
 ## TypeScript

src/generate/generateBigInt.ts

@@ -1,31 +1,86 @@
 export const defaultAlphabet =
   'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
 
-export function generator(alphabet?: string) {
-  // remove duplicates from alphabets
-  const cleanAlphabet = (alphabet: string) => {
-    return Array.from(new Set(alphabet.split(''))).join('')
+function cleanAlphabet(alphabet: string) {
+  return Array.from(new Set(alphabet.split(''))).join('')
+}
+
+// calculates the level of a given index in the current virtual tree
+const getLevel = (base: bigint, index: bigint): bigint => {
+  let level = 0n
+  let current = index
+  let parent: bigint
+  while (current > 0n) {
+    parent = (current - 1n) / base
+    level++
+    current = parent
   }
+  return level
+}
 
-  if (typeof alphabet !== 'undefined' && typeof alphabet !== 'string') {
-    throw new TypeError('alphabet must be a string')
+// Generates a string based on the given index and alphabet
+function generateString(startIndex: bigint, alphabet: string): string {
+  if (startIndex === 0n) return ''
+  const n = BigInt(alphabet.length)
+  let result = ''
+  let l: bigint
+  let f: bigint
+  let rebasedPos: bigint
+  let rebasedIndex: bigint
+  let index = startIndex
+  while (index > 0n) {
+    l = getLevel(n, index)
+    f = 0n
+    for (let i = 0n; i < l; i++) {
+      f += n ** i
+    }
+    rebasedPos = index - f
+    rebasedIndex = ((rebasedPos % n) + n) % n // ensure non-negative
+    result = alphabet[Number(rebasedIndex)] + result
+    index = (index - 1n) / n
   }
+  return result
+}
 
-  const cleanedAlphabet = alphabet ? cleanAlphabet(alphabet) : defaultAlphabet
+export type GenOptions = {
+  alphabet?: string
+  from?: bigint
+  to?: bigint
+  maxLen?: number
+  maxIterations?: number
+}
 
-  // string generation function
-  const generate = (index: number | bigint) => {
-    return typeof index === 'bigint'
-      ? generateBigInt(index, cleanedAlphabet)
-      : generateInt(index as number, cleanedAlphabet)
-  }
+export function* indexedStringVariation(options: GenOptions) {
+  const alphabet = options.alphabet
+    ? cleanAlphabet(options.alphabet)
+    : defaultAlphabet
+  const from = options.from ?? 0n
 
-  generate.alphabet = cleanedAlphabet
+  let iterations = 0
+  let i = from
 
-  return generate
-}
+  while (true) {
+    const str = generateString(i, alphabet)
+
+    if (options.maxLen !== undefined && str.length > options.maxLen) {
+      break
+    }
+    yield str
+
+    i++
+    iterations++
 
-import generateBigInt from './generate/generateBigInt.js'
-import generateInt from './generate/generateInt.js'
+    if (options.to !== undefined && i > options.to) {
+      break
+    }
+
+    if (
+      options.maxIterations !== undefined &&
+      iterations >= options.maxIterations
+    ) {
+      break
+    }
+  }
+}
 
-export default generator
+export default indexedStringVariation

src/generate/generateInt.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it } from 'vitest'
-import { defaultAlphabet, generator } from './index.js'
+import { indexedStringVariation, type GenOptions } from './index.js'
 
-const cases: [string, string, string[]][] = [
+const cases: [string, GenOptions, string[]][] = [
   [
     'it should produce variations with digits in alphabet',
-    '0123456789',
+    { alphabet: '0123456789', from: 0n, to: 21n },
     [
       '',
       '0',
@@ -32,7 +32,7 @@ const cases: [string, string, string[]][] = [
   ],
   [
     'it should produce variations with alphanumeric alphabet',
-    'abc1',
+    { alphabet: 'abc1', from: 0n, to: 21n },
     [
       '',
       'a',
@@ -60,7 +60,7 @@ const cases: [string, string, string[]][] = [
   ],
   [
     'it should remove duplicates from alphabet',
-    'aabbbbcc1111111',
+    { alphabet: 'aabbbbcc1111111', from: 0n, to: 21n },
     [
       '',
       'a',
@@ -86,48 +86,30 @@ const cases: [string, string, string[]][] = [
       'aaa',
     ],
   ],
+  [
+    'it uses the default alphabet if none is provided',
+    { from: 0n, to: 10n },
+    ['', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'],
+  ],
+  [
+    'it stops at maxLen if provided',
+    { alphabet: 'ab', maxLen: 2 },
+    ['', 'a', 'b', 'aa', 'ab', 'ba', 'bb'],
+  ],
+  [
+    'it stops at maxIterations if provided',
+    { alphabet: 'ab', maxIterations: 5 },
+    ['', 'a', 'b', 'aa', 'ab'],
+  ],
 ]
 
 describe('indexed-string-variation', () => {
   it.each(cases)(
     '%s',
-    (_title: string, alphabet: string, expected: string[]) => {
-      const isvn = generator(alphabet)
-      const generatedInt: string[] = []
-      const generatedBigInt: string[] = []
-      for (let i = 0; i < expected.length; i++) {
-        generatedInt.push(isvn(i))
-        generatedBigInt.push(isvn(BigInt(i)))
-      }
-      expect(generatedInt).toEqual(expected)
-      expect(generatedBigInt).toEqual(expected)
+    (_title: string, options: GenOptions, expected: string[]) => {
+      const isvn = indexedStringVariation(options)
+      const generatedStrings = [...isvn]
+      expect(generatedStrings).toEqual(expected)
     },
   )
-
-  it('it must use the default alphabet if no alphabet is given', () => {
-    const g = generator()
-    expect(g.alphabet).toBe(defaultAlphabet)
-  })
-
-  it('throws TypeError for invalid integer indices', () => {
-    const isvn = generator('abc')
-    // Not an integer
-    expect(() => isvn(1.5)).toThrow(TypeError)
-    expect(() => isvn(Number.NaN)).toThrow(TypeError)
-    expect(() => isvn(Number.POSITIVE_INFINITY)).toThrow(TypeError)
-    // Negative number
-    expect(() => isvn(-1)).toThrow(TypeError)
-    // Negative BigInt
-    expect(() => isvn(BigInt(-1))).toThrow(TypeError)
-    // Not a number or bigint
-    expect(() => isvn('foo' as unknown as number)).toThrow(TypeError)
-  })
-
-  it('throws TypeError if an invalid alphabet is passed', () => {
-    expect(() => generator(123 as unknown as string)).toThrow(TypeError)
-    expect(() => generator({} as unknown as string)).toThrow(TypeError)
-    expect(() => generator([] as unknown as string)).toThrow(TypeError)
-    expect(() => generator(null as unknown as string)).toThrow(TypeError)
-    expect(() => generator(undefined)).not.toThrow() // undefined is allowed (will use the default alphabet)
-  })
 })