refactor: change separate tools by category

core/stdlib/src/text/index.ts

@@ -0,0 +1,4 @@
+export * from './levenshtein-distance';
+export * from './trigram-distance';
+// TODO: Template is not implemented yet
+// export * from './template';

core/stdlib/src/text/levenshtein-distance/index.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import {levenshteinDistance} from '.';
+  
+describe('levenshteinDistance', () => {
+    it('calculate edit distance between two strings', () => {  
+      // just one substitution I at the beginning
+      expect(levenshteinDistance('islander', 'slander')).toBe(1);
+  
+      // substitution M->K, T->M and add an A to the end
+      expect(levenshteinDistance('mart', 'karma')).toBe(3);
+  
+      // substitution K->S, E->I and insert G at the end
+      expect(levenshteinDistance('kitten', 'sitting')).toBe(3);
+  
+      // should add 4 letters FOOT at the beginning
+      expect(levenshteinDistance('ball', 'football')).toBe(4);
+  
+      // should delete 4 letters FOOT at the beginning
+      expect(levenshteinDistance('football', 'foot')).toBe(4);
+  
+      // needs to substitute the first 5 chars INTEN->EXECU
+      expect(levenshteinDistance('intention', 'execution')).toBe(5);
+    });
+
+    it('handle empty strings', () => {
+      expect(levenshteinDistance('', '')).toBe(0);
+      expect(levenshteinDistance('a', '')).toBe(1);
+      expect(levenshteinDistance('', 'a')).toBe(1);
+      expect(levenshteinDistance('abc', '')).toBe(3);
+      expect(levenshteinDistance('', 'abc')).toBe(3);
+    });
+  });

core/stdlib/src/text/levenshtein-distance/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @name levenshteinDistance
+ * @category Text
+ * @description Calculate the Levenshtein distance between two strings
+ * 
+ * @param {string} left First string
+ * @param {string} right Second string
+ * @returns {number} The Levenshtein distance between the two strings
+ *
+ * @since 0.0.1
+ */
+export function levenshteinDistance(left: string, right: string): number {
+    if (left === right) return 0;
+
+    if (left.length === 0) return right.length;
+    if (right.length === 0) return left.length;
+
+    // Create empty edit distance matrix for all possible modifications of
+    // substrings of left to substrings of right
+    const distanceMatrix = Array(right.length + 1).fill(null).map(() => Array(left.length + 1).fill(null));
+
+    // Fill the first row of the matrix
+    // If this is the first row, we're transforming from an empty string to left
+    // In this case, the number of operations equals the length of left substring
+    for (let i = 0; i <= left.length; i++)
+        distanceMatrix[0]![i]! = i;
+
+    // Fill the first column of the matrix
+    // If this is the first column, we're transforming empty string to right
+    // In this case, the number of operations equals the length of right substring
+    for (let j = 0; j <= right.length; j++)
+        distanceMatrix[j]![0]! = j;
+
+    for (let j = 1; j <= right.length; j++) {
+        for (let i = 1; i <= left.length; i++) {
+            const indicator = left[i - 1] === right[j - 1] ? 0 : 1;
+            distanceMatrix[j]![i]! = Math.min(
+                distanceMatrix[j]![i - 1]! + 1, // deletion
+                distanceMatrix[j - 1]![i]! + 1, // insertion
+                distanceMatrix[j - 1]![i - 1]! + indicator // substitution
+            );
+        }
+    }
+
+    return distanceMatrix[right.length]![left.length]!;
+}

core/stdlib/src/text/template/index.test-d.ts

@@ -0,0 +1,105 @@
+import { describe, expectTypeOf, it } from "vitest";
+import type { ClearPlaceholder, ExtractPlaceholders } from "./index";
+
+describe('template', () => {
+  describe('ClearPlaceholder', () => {
+    it('ignores strings without braces', () => {
+      type actual = ClearPlaceholder<'name'>;
+      type expected = 'name';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('removes all balanced braces from placeholders', () => {
+      type actual1 = ClearPlaceholder<'{name}'>;
+      type actual2 = ClearPlaceholder<'{{name}}'>;
+      type actual3 = ClearPlaceholder<'{{{name}}}'>;
+      type expected = 'name';
+
+      expectTypeOf<actual1>().toEqualTypeOf<expected>();
+      expectTypeOf<actual2>().toEqualTypeOf<expected>();
+      expectTypeOf<actual3>().toEqualTypeOf<expected>();
+    });
+
+    it('removes all unbalanced braces from placeholders', () => {
+      type actual1 = ClearPlaceholder<'{name}}'>;
+      type actual2 = ClearPlaceholder<'{{name}}}'>;
+      type expected = 'name';
+
+      expectTypeOf<actual1>().toEqualTypeOf<expected>();
+      expectTypeOf<actual2>().toEqualTypeOf<expected>();
+    });
+  });
+
+  describe('ExtractPlaceholders', () => {
+    it('string without placeholders', () => {
+      type actual = ExtractPlaceholders<'Hello name, how are?'>;
+      type expected = never;
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with one idexed placeholder', () => {
+      type actual = ExtractPlaceholders<'Hello {0}, how are you?'>;
+      type expected = '0';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with two indexed placeholders', () => {
+      type actual = ExtractPlaceholders<'Hello {0}, my name is {1}'>;
+      type expected = '0' | '1';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with one key placeholder', () => {
+      type actual = ExtractPlaceholders<'Hello {name}, how are you?'>;
+      type expected = 'name';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with two key placeholders', () => {
+      type actual = ExtractPlaceholders<'Hello {name}, my name is {managers.0.name}'>;
+      type expected = 'name' | 'managers.0.name';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with mixed placeholders', () => {
+      type actual = ExtractPlaceholders<'Hello {0}, how are you? My name is {1.name}'>;
+      type expected = '0' | '1.name';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with nested placeholder and balanced braces', () => {
+      type actual = ExtractPlaceholders<'Hello {{name}}, how are you?'>;
+      type expected = 'name';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with nested placeholder and unbalanced braces', () => {
+      type actual = ExtractPlaceholders<'Hello {{{name}, how are you?'>;
+      type expected = 'name';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with nested placeholders and balanced braces', () => {
+      type actual = ExtractPlaceholders<'Hello {{{name}{positions}}}, how are you?'>;
+      type expected = 'name' | 'positions';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+
+    it('string with nested placeholders and unbalanced braces', () => {
+      type actual = ExtractPlaceholders<'Hello {{{name}{positions}, how are you?'>;
+      type expected = 'name' | 'positions';
+
+      expectTypeOf<actual>().toEqualTypeOf<expected>();
+    });
+  });
+});

core/stdlib/src/text/template/index.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { templateObject } from '.';
+
+describe.todo('templateObject', () => {
+  it('replace template placeholders with corresponding values from args', () => {
+    const template = 'Hello, {names.0}!';
+    const args = { names: ['John'] };
+    const result = templateObject(template, args);
+    expect(result).toBe('Hello, John!');
+  });
+
+  it('replace template placeholders with corresponding values from args', () => {
+    const template = 'Hello, {name}!';
+    const args = { name: 'John' };
+    const result = templateObject(template, args);
+    expect(result).toBe('Hello, John!');
+  });
+
+  it('replace template placeholders with fallback value if corresponding value is undefined', () => {
+    const template = 'Hello, {name}!';
+    const args = { age: 25 };
+    const fallback = 'Guest';
+    const result = templateObject(template, args, fallback);
+    expect(result).toBe('Hello, Guest!');
+  });
+
+  it(' replace template placeholders with fallback value returned by fallback function if corresponding value is undefined', () => {
+    const template = 'Hello, {name}!';
+    const args = { age: 25 };
+    const fallback = (key: string) => `Unknown ${key}`;
+    const result = templateObject(template, args, fallback);
+    expect(result).toBe('Hello, Unknown name!');
+  });
+
+  it('replace template placeholders with nested values from args', () => {
+      const result = templateObject('Hello {{user.name}, your address {user.addresses.0.street}', {
+        user: {
+         name: 'John Doe',
+         addresses: [
+           { street: '123 Main St', city: 'Springfield'},
+           { street: '456 Elm St', city: 'Shelbyville'}
+         ]
+       }
+     });
+
+      expect(result).toBe('Hello {John Doe, your address 123 Main St');
+  });
+});

core/stdlib/src/text/template/index.ts

@@ -0,0 +1,65 @@
+import { getByPath, type Generate } from '../../collections';
+import { isFunction } from '../../types';
+
+/**
+ * Type of a value that will be used to replace a placeholder in a template.
+ */
+type StringPrimitive = string | number | bigint | null | undefined;
+
+/**
+ * Type of a fallback value when a template key is not found.
+ */
+type TemplateFallback = string | ((key: string) => string);
+
+/**
+ * Type of an object that will be used to replace placeholders in a template.
+ */
+type TemplateArgsObject = StringPrimitive[] | { [key: string]: TemplateArgsObject | StringPrimitive };
+
+/**
+ * Type of a template string with placeholders.
+ */
+const TEMPLATE_PLACEHOLDER = /{([^{}]+)}/gm;
+
+/**
+ * Removes the placeholder syntax from a template string.
+ * 
+ * @example
+ * type Base = ClearPlaceholder<'{user.name}'>; // 'user.name'
+ * type Unbalanced = ClearPlaceholder<'{user.name'>; // 'user.name'
+ */
+export type ClearPlaceholder<T extends string> =
+  T extends `${string}{${infer Template}`
+    ? ClearPlaceholder<Template>
+    : T extends `${infer Template}}${string}`
+      ? ClearPlaceholder<Template>
+      : T;
+
+/**
+ * Extracts all placeholders from a template string.
+ * 
+ * @example
+ * type Base = ExtractPlaceholders<'Hello {user.name}, {user.addresses.0.street}'>; // 'user.name' | 'user.addresses.0.street'
+ */
+export type ExtractPlaceholders<T extends string> =
+  T extends `${infer Before}}${infer After}`
+    ? Before extends `${string}{${infer Placeholder}`
+      ? ClearPlaceholder<Placeholder> | ExtractPlaceholders<After>
+      : ExtractPlaceholders<After>
+    : never;
+
+export function templateObject<T extends string, A extends Generate<ExtractPlaceholders<T>>>(template: T, args: A, fallback?: TemplateFallback): string {
+    return template.replace(TEMPLATE_PLACEHOLDER, (_, key) => {    
+        const value = getByPath(args, key) as string;
+        return value !== undefined ? value : (isFunction(fallback) ? fallback(key) : '');
+    });
+}
+
+// templateObject('Hello {user.name}, your address {user.addresses.0.street}', {
+//   user: {
+//     name: 'John',
+//     addresses: [
+//       { city: 'New York', street: '5th Avenue' },
+//     ],
+//   },
+// });

core/stdlib/src/text/trigram-distance/index.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { trigramDistance, trigramProfile } from '.';
+
+describe('trigramProfile', () => {
+    it('trigram profile of a text with different trigrams', () => {
+        const different_trigrams = 'hello world';
+        const profile1 = trigramProfile(different_trigrams);
+
+        expect(profile1).toEqual(new Map([
+            ['\n\nh', 1],
+            ['\nhe', 1],
+            ['hel', 1],
+            ['ell', 1],
+            ['llo', 1],
+            ['lo ', 1],
+            ['o w', 1],
+            [' wo', 1],
+            ['wor', 1],
+            ['orl', 1],
+            ['rld', 1],
+            ['ld\n', 1],
+            ['d\n\n', 1]
+        ]));
+    });
+
+    it('trigram profile of a text with repeated trigrams', () => {
+        const repeated_trigrams = 'hello hello';
+        const profile2 = trigramProfile(repeated_trigrams);
+
+        expect(profile2).toEqual(new Map([
+            ['\n\nh', 1],
+            ['\nhe', 1],
+            ['hel', 2],
+            ['ell', 2],
+            ['llo', 2],
+            ['lo ', 1],
+            ['o h', 1],
+            [' he', 1],
+            ['lo\n', 1],
+            ['o\n\n', 1]
+        ]));
+    });
+
+    it('trigram profile of an empty text', () => {
+        const text = '';
+        const profile = trigramProfile(text);
+
+        expect(profile).toEqual(new Map([
+            ['\n\n\n', 2],
+        ]));
+    });
+});
+
+describe('trigramDistance', () => {
+    it('zero when comparing the same text', () => {
+        const profile1 = trigramProfile('hello world');
+        const profile2 = trigramProfile('hello world');
+
+        expect(trigramDistance(profile1, profile2)).toBe(0);
+    });
+
+    it('one for completely different text', () => {
+        const profile1 = trigramProfile('hello world');
+        const profile2 = trigramProfile('lorem ipsum');
+
+        expect(trigramDistance(profile1, profile2)).toBe(1);
+    });
+
+    it('one for empty text and non-empty text', () => {
+        const profile1 = trigramProfile('hello world');
+        const profile2 = trigramProfile('');
+
+        expect(trigramDistance(profile1, profile2)).toBe(1);
+    });
+
+    it('approximately 0.5 for similar text', () => {
+        const profile1 = trigramProfile('hello world');
+        const profile2 = trigramProfile('hello lorem');
+
+        const approx = trigramDistance(profile1, profile2);
+
+        expect(approx).toBeGreaterThan(0.45);
+        expect(approx).toBeLessThan(0.55);
+    });
+
+    it('triangle inequality', () => {
+        const A = trigramDistance(trigramProfile('metric'), trigramProfile('123ric'));
+        const B = trigramDistance(trigramProfile('123ric'), trigramProfile('123456'));
+        const C = trigramDistance(trigramProfile('metric'), trigramProfile('123456'));
+
+        expect(A + B).toBeGreaterThanOrEqual(C);
+    });
+});

core/stdlib/src/text/trigram-distance/index.ts

@@ -0,0 +1,57 @@
+export type Trigrams = Map<string, number>;
+
+/**
+ * @name trigramProfile
+ * @category Text
+ * @description Extracts trigrams from a text and returns a map of trigram to count
+ * 
+ * @param {string} text The text to extract trigrams
+ * @returns {Trigrams} A map of trigram to count
+ *
+ * @since 0.0.1
+ */
+export function trigramProfile(text: string): Trigrams {
+    text = '\n\n' + text + '\n\n';
+
+    const trigrams = new Map<string, number>();
+
+    for (let i = 0; i < text.length - 2; i++) {
+        const trigram = text.slice(i, i + 3);
+        const count = trigrams.get(trigram) ?? 0;
+        trigrams.set(trigram, count + 1);
+    }
+
+    return trigrams;
+}
+
+/**
+ * @name trigramDistance
+ * @category Text
+ * @description Calculates the trigram distance between two strings
+ * 
+ * @param {Trigrams} left First text trigram profile
+ * @param {Trigrams} right Second text trigram profile
+ * @returns {number} The trigram distance between the two strings
+ *
+ * @since 0.0.1
+ */
+export function trigramDistance(left: Trigrams, right: Trigrams): number {
+    let distance = -4;
+    let total = -4;
+
+    for (const [trigram, left_count] of left) {
+        total += left_count;
+        const right_count = right.get(trigram) ?? 0;
+        distance += Math.abs(left_count - right_count);
+    }
+
+    for (const [trigram, right_count] of right) {
+        total += right_count;
+        const left_count = left.get(trigram) ?? 0;
+        distance += Math.abs(left_count - right_count);
+    }
+
+    if (distance < 0) return 0;
+
+    return distance / total;
+}