1.1.10

fix(documentation): Update documentation and migration guide with standardized method names and deprecation notices.
1.1.9
2025-05-15 08:56:05 +00:00 · 2025-05-15 08:56:05 +00:00 · 2025-05-12 23:23:49 +00:00 · 2025-05-12 23:23:49 +00:00 · 2025-05-12 13:42:49 +00:00 · 2025-05-12 13:42:49 +00:00
24 changed files with 11336 additions and 26105 deletions
--- a/.gitea/workflows/default_nottags.yaml
+++ b/.gitea/workflows/default_nottags.yaml
@ -0,0 +1,66 @@
+name: Default (not tags)
+
+on:
+  push:
+    tags-ignore:
+      - '**'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
+  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install pnpm and npmci
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+
+      - name: Run npm prepare
+        run: npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    if: ${{ always() }}
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm build
--- a/.gitea/workflows/default_tags.yaml
+++ b/.gitea/workflows/default_tags.yaml
@ -0,0 +1,124 @@
+name: Default (tags)
+
+on:
+  push:
+    tags:
+      - '*'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
+  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    if: ${{ always() }}
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm build
+
+  release:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Release
+        run: |
+          npmci node install stable
+          npmci npm publish
+
+  metadata:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Code quality
+        run: |
+          npmci command npm install -g typescript
+          npmci npm install
+
+      - name: Trigger
+        run: npmci trigger
+
+      - name: Build docs and upload artifacts
+        run: |
+          npmci node install stable
+          npmci npm install
+          pnpm install -g @git.zone/tsdoc
+          npmci command tsdoc
+        continue-on-error: true
--- a/.gitignore
+++ b/.gitignore
@ -3,7 +3,6 @@
 # artifacts
 coverage/
 public/
-pages/

 # installs
 node_modules/
@ -17,4 +16,5 @@ node_modules/
 dist/
 dist_*/

-# custom
+#------# custom
+**/.claude/settings.local.json
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@ -1,138 +0,0 @@
-# gitzone ci_default
-image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-
-cache:
-  paths:
-    - .npmci_cache/
-  key: '$CI_BUILD_STAGE'
-
-stages:
-  - security
-  - test
-  - release
-  - metadata
-
-# ====================
-# security stage
-# ====================
-mirror:
-  stage: security
-  script:
-    - npmci git mirror
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-auditProductionDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --production --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=prod --production
-  tags:
-    - docker
-  allow_failure: true
-
-auditDevDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=dev
-  tags:
-    - docker
-  allow_failure: true
-
-# ====================
-# test stage
-# ====================
-
-testStable:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci npm test
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-testBuild:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci command npm run build
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-release:
-  stage: release
-  script:
-    - npmci node install stable
-    - npmci npm publish
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-# ====================
-# metadata stage
-# ====================
-codequality:
-  stage: metadata
-  allow_failure: true
-  only:
-    - tags
-  script:
-    - npmci command npm install -g tslint typescript
-    - npmci npm prepare
-    - npmci npm install
-    - npmci command "tslint -c tslint.json ./ts/**/*.ts"
-  tags:
-    - lossless
-    - docker
-    - priv
-
-trigger:
-  stage: metadata
-  script:
-    - npmci trigger
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-pages:
-  stage: metadata
-  script:
-    - npmci node install lts
-    - npmci command npm install -g @gitzone/tsdoc
-    - npmci npm prepare
-    - npmci npm install
-    - npmci command tsdoc
-  tags:
-    - lossless
-    - docker
-    - notpriv
-  only:
-    - tags
-  artifacts:
-    expire_in: 1 week
-    paths:
-      - public
-  allow_failure: true
--- a/changelog.md
+++ b/changelog.md
@ -0,0 +1,76 @@
+# Changelog
+
+## 2025-05-13 - 1.1.10 - fix(documentation)
+Update documentation and migration guide with standardized method names and deprecation notices.
+
+- Replaced deprecated getClosestMatchForString with findClosestMatch in code examples.
+- Replaced deprecated getChangeScoreForString with calculateScores in documentation.
+- Updated readme plan to mark method naming standardization as completed.
+
+## 2025-05-12 - 1.1.9 - fix(core)
+Update build scripts, refine testing assertions, and enhance documentation
+
+- Updated .gitignore to exclude local settings files
+- Modified build script in package.json to use 'tsbuild tsfolders --allowimplicitany'
+- Revised readme.plan.md with comprehensive Fuse.js optimization and API improvement strategies
+- Enhanced input validation, error handling, and JSDoc comments across core classes
+- Standardized test syntax and improved test coverage for fuzzy matching features
+
+## 2025-05-12 - 1.1.8 - fix(tests)
+Standardize test syntax and update testing dependencies
+
+- Added @git.zone/tsrun dependency to package.json for improved test runner support
+- Refactored test export in test/test.articlesearch.ts to use default export instead of tap.start()
+- Updated readme.plan.md to describe testing improvements and syntax standardization
+
+## 2025-05-12 - 1.1.7 - fix(build)
+Fix import paths, update CI workflows and upgrade dependencies for ESM compliance
+
+- Updated import statements to include .js extensions for NodeNext compatibility
+- Upgraded dependencies: @push.rocks/smartpromise (^4.0.2), @tsclass/tsclass (^9.2.0), fuse.js (^7.1.0), leven (^4.0.0), and @push.rocks/tapbundle (^6.0.3)
+- Added new workflow files for CI (default_tags.yaml and default_nottags.yaml)
+- Revised test files and documentation to reflect file path and dependency changes
+- Minor adjustments in package.json (scripts and metadata) and tsconfig for enhanced module resolution
+
+## 2024-05-29 - 1.1.6 - maintenance  
+This release brings a series of configuration and documentation updates as well as an organizational change.  
+- Updated project description.  
+- Revised tsconfig settings.  
+- Updated npmextra.json with new githost details (merged from several commits).  
+- Switched to a new organization scheme.  
+(Note: A prior commit “1.1.6” from 2021 was a version bump and is omitted here.)
+
+## 2021-10-04 - 1.1.5 - core  
+Core components were fixed in this update.  
+- fix(core): update
+
+## 2021-10-03 - 1.1.4  
+This version was released as a version bump without additional significant changes.
+
+## 2021-10-03 - 1.1.3 - core  
+Minor fixes were applied to core functionality.  
+- fix(core): update
+
+## 2021-10-03 - 1.1.2 - core  
+Additional improvements and fixes to the core components.  
+- fix(core): update
+
+## 2021-10-03 - 1.1.1 - core  
+A further core update fixing underlying issues.  
+- fix(core): update
+
+## 2018-08-19 - 1.1.0 - Smartfuzzy  
+A fix was introduced for Smartfuzzy’s matching functionality.  
+- fix(Smartfuzzy.getClosestMatchForString() now returns the cloesest string directly): update
+
+## 2018-08-19 - 1.0.3 - ObjectSorter  
+A new feature has been added to sort objects by likability.  
+- feat(ObjectSorter): now sorts objects by likability
+
+## 2018-08-19 - 1.0.2 - package  
+An adjustment was made to the package name in the npm configuration.  
+- fix(package): npm name
+
+## 2018-08-19 - 1.0.1 - package  
+Initial package fixes were applied.  
+- fix(package): initial
--- a/19
+++ b/19
@ -0,0 +1,19 @@
+Copyright (c) 2014 Lossless GmbH (hello@lossless.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/npmextra.json
+++ b/npmextra.json
@ -2,16 +2,32 @@
  "gitzone": {
    "projectType": "npm",
    "module": {
-      "githost": "gitlab.com",
-      "gitscope": "pushrocks",
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
      "gitrepo": "smartfuzzy",
      "shortDescription": "search things easily",
-      "npmPackagename": "@pushrocks/smartfuzzy",
-      "license": "MIT"
+      "npmPackagename": "@push.rocks/smartfuzzy",
+      "license": "MIT",
+      "description": "A library for fuzzy matching strings against word dictionaries or arrays, with support for object and article searching.",
+      "keywords": [
+        "fuzzy matching",
+        "string matching",
+        "dictionary matching",
+        "search",
+        "text analysis",
+        "object sorting",
+        "article search",
+        "text similarity",
+        "keyword matching",
+        "data filtering"
+      ]
    }
  },
  "npmci": {
    "npmGlobalTools": [],
    "npmAccessLevel": "public"
+  },
+  "tsdoc": {
+    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
  }
 }
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@ -1,8 +1,8 @@
 {
-  "name": "@pushrocks/smartfuzzy",
-  "version": "1.1.4",
+  "name": "@push.rocks/smartfuzzy",
+  "version": "1.1.10",
  "private": false,
-  "description": "fuzzy match strings against word dictionaries/arrays",
+  "description": "A library for fuzzy matching strings against word dictionaries or arrays, with support for object and article searching.",
  "main": "dist_ts/index.js",
  "typings": "dist_ts/index.d.ts",
  "author": "Lossless GmbH",
@ -10,19 +10,21 @@
  "scripts": {
    "test": "(tstest test/)",
    "format": "(gitzone format)",
-    "build": "(tsbuild)"
+    "build": "(tsbuild tsfolders --allowimplicitany)",
+    "buildDocs": "tsdoc"
  },
  "devDependencies": {
-    "@gitzone/tsbuild": "^2.1.27",
-    "@gitzone/tstest": "^1.0.57",
-    "@pushrocks/tapbundle": "^3.2.14",
-    "@types/node": "^16.10.2"
+    "@git.zone/tsbuild": "^2.1.27",
+    "@git.zone/tsrun": "^1.3.3",
+    "@git.zone/tstest": "^1.0.57",
+    "@push.rocks/tapbundle": "^6.0.3",
+    "@types/node": "^22.15.17"
  },
  "dependencies": {
-    "@pushrocks/smartpromise": "^3.1.6",
-    "@tsclass/tsclass": "^3.0.33",
-    "fuse.js": "^6.4.6",
-    "leven": "^3.1.0"
+    "@push.rocks/smartpromise": "^4.0.2",
+    "@tsclass/tsclass": "^9.2.0",
+    "fuse.js": "^7.1.0",
+    "leven": "^4.0.0"
  },
  "browserslist": [
    "last 1 chrome versions"
@ -38,5 +40,30 @@
    "cli.js",
    "npmextra.json",
    "readme.md"
-  ]
+  ],
+  "keywords": [
+    "fuzzy matching",
+    "string matching",
+    "dictionary matching",
+    "search",
+    "text analysis",
+    "object sorting",
+    "article search",
+    "text similarity",
+    "keyword matching",
+    "data filtering"
+  ],
+  "homepage": "https://code.foss.global/push.rocks/smartfuzzy#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://code.foss.global/push.rocks/smartfuzzy.git"
+  },
+  "bugs": {
+    "url": "https://code.foss.global/push.rocks/smartfuzzy/issues"
+  },
+  "type": "module",
+  "pnpm": {
+    "overrides": {}
+  },
+  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
 }
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/readme.hints.md
+++ b/readme.hints.md
@ -0,0 +1 @@
+ 
--- a/readme.md
+++ b/readme.md
@ -0,0 +1,135 @@
+# @push.rocks/smartfuzzy
+
+fuzzy match strings against word dictionaries/arrays
+
+## Install
+
+To install `@push.rocks/smartfuzzy`, use the following npm command. It's recommended to do this in a project where TypeScript is already configured:
+
+```bash
+npm install @push.rocks/smartfuzzy --save
+```
+
+## Usage
+
+`@push.rocks/smartfuzzy` is a versatile library designed to help you perform fuzzy searches and sorts on arrays of strings and objects. Whether you're building a search feature, organizing data, or implementing autocomplete functionality, `@push.rocks/smartfuzzy` offers you the tools needed to achieve efficient and intuitive search results. Below are various scenarios to cover a broad set of features of the module, ensuring you can integrate it effectively into your TypeScript projects.
+
+### Setting Up
+
+First, ensure you import the necessary components:
+
+```typescript
+import { Smartfuzzy, ObjectSorter, ArticleSearch } from '@push.rocks/smartfuzzy';
+```
+
+### Basic String Matching
+
+For scenarios where you have an array of strings and you wish to find a match for a search term:
+
+```typescript
+const myDictionary = ['Sony', 'Deutsche Bahn', 'Apple Inc.', "Trader Joe's"];
+const mySmartFuzzy = new Smartfuzzy(myDictionary);
+
+// Adding additional dictionary entries
+mySmartFuzzy.addToDictionary('Microsoft');
+mySmartFuzzy.addToDictionary(['Google', 'Facebook']);
+
+// Finding the closest match
+const searchResult = mySmartFuzzy.findClosestMatch('Appl');
+console.log(searchResult); // Output: "Apple Inc."
+
+// Calculate similarity scores for all dictionary entries
+const scores = mySmartFuzzy.calculateScores('Appl');
+console.log(scores);
+// Output: { 'Sony': 4, 'Deutsche Bahn': 11, 'Apple Inc.': 5, ... }
+// Lower scores indicate better matches
+```
+
+This example demonstrates how to instantiate the `Smartfuzzy` class with a list of strings (dictionary) and add more entries to it. You can then use it to find the closest match or calculate similarity scores for a given search string.
+
+> **Note:** The older method names `getClosestMatchForString` and `getChangeScoreForString` are still available for backward compatibility but are deprecated. It's recommended to use the new method names `findClosestMatch` and `calculateScores` instead.
+
+### Advanced Object Sorting
+
+Imagine you are managing a list of objects, and you wish to sort them based on the resemblance of one or more of their properties to a search term:
+
+```typescript
+interface ICar {
+  brand: string;
+  model: string;
+}
+
+const carList: ICar[] = [
+  { brand: 'BMW', model: 'M3' },
+  { brand: 'Mercedes Benz', model: 'E-Class' },
+  { brand: 'Volvo', model: 'XC90' },
+];
+
+const carSorter = new ObjectSorter<ICar>(carList);
+
+// Search and sort based on brand similarity
+const searchResults = carSorter.sort('Benz', ['brand']);
+console.log(searchResults); // Results will be sorted by relevance to 'Benz'
+```
+
+This scenario shows how to use `ObjectSorter` for sorting an array of objects based on how closely one of their string properties matches a search term. This is particularly useful for filtering or autocomplete features where relevance is key.
+
+### Searching Within Articles
+
+If your application involves searching through articles or similar textual content, `ArticleSearch` allows for a weighted search across multiple fields:
+
+```typescript
+import { IArticle } from '@tsclass/tsclass/content';
+
+const articles: IArticle[] = [
+  {
+    title: 'History of Berlin',
+    content: 'Berlin has a rich history...',
+    tags: ['history', 'Berlin'],
+    timestamp: Date.now(),
+    featuredImageUrl: null,
+    url: null,
+  },
+  {
+    title: 'Tourism in Berlin',
+    content: 'Discover the vibrant city of Berlin...',
+    tags: ['travel', 'Berlin'],
+    timestamp: Date.now(),
+    featuredImageUrl: null,
+    url: null,
+  },
+];
+
+const articleSearch = new ArticleSearch(articles);
+
+// Perform a search across titles, content, and tags
+const searchResult = await articleSearch.search('rich history');
+console.log(searchResult); // Array of matches with relevance to 'rich history'
+```
+
+The `ArticleSearch` class showcases how to implement a search feature across a collection of articles with prioritization across different fields (e.g., title, content, tags). This ensures more relevant search results and creates a better experience for users navigating through large datasets or content libraries.
+
+### Conclusion
+
+`@push.rocks/smartfuzzy` offers a robust set of functionalities for integrating fuzzy searching and sorting capabilities into your TypeScript applications. By following the examples demonstrated, you can effectively utilize the module to enhance user experience where text search is a critical component of the application.
+
+Remember to always consider the specific requirements of your project when implementing these features, as adjustments to configurations such as threshold levels and keys to search on can significantly impact the effectiveness of your search functionality.
+
+## License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH  
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
--- a/readme.plan.md
+++ b/readme.plan.md
@ -0,0 +1,172 @@
+# SmartFuzzy Improvement Plan - Fuse.js Optimization Focus
+
+## Current Status
+- ESM imports/exports fixed with .js extensions
+- Basic fuzzy matching functionality works
+- Testing infrastructure fixed with @git.zone/tsrun dependency
+- Test syntax standardized using SmartExpect syntax
+- Tests improved with proper assertions and error handling
+- Input validation added to all public methods
+- Code documented with comprehensive TypeScript JSDoc comments
+- Method names standardized for better API consistency
+- Backward compatibility maintained through deprecated method aliases
+
+## Improvement Plan - Fuse.js Optimization Focus
+
+### 1. Fully Leverage Fuse.js Capabilities
+
+#### 1.1 Enhance Configurability
+- [ ] Create a comprehensive `FuzzyOptions` interface exposing Fuse.js options
+  - **Implementation approach**:
+    - Expose all relevant Fuse.js options (threshold, distance, location, etc.)
+    - Group options logically (matching control, performance control, output control)
+    - Add proper TypeScript types and documentation for each option
+    - Create sensible defaults for different use cases (loose matching, exact matching, etc.)
+    - Add option validation with clear error messages
+    - Implement runtime option updates via setOptions() method
+
+#### 1.2 Improve Weighted Field Support
+- [ ] Enhance ObjectSorter to support field weights like ArticleSearch
+  - **Implementation approach**:
+    - Add ability to specify weight per field in ObjectSorter
+    - Maintain backward compatibility with current simple array of fields
+    - Create examples of different weighting strategies
+    - Add tests demonstrating the effect of different field weights
+    - Include weight settings in all relevant documentation
+
+#### 1.3 Add Extended Search Capabilities
+- [ ] Implement Fuse.js extended search syntax support
+  - **Implementation approach**:
+    - Add support for Fuse.js extended search syntax (AND, OR, exact matching)
+    - Create helper methods to build complex search queries
+    - Add examples of extended search usage in documentation
+    - Create tests for complex search patterns
+    - Implement query validation for extended search syntax
+
+### 2. Performance Optimization
+
+#### 2.1 Optimize Index Creation
+- [ ] Implement proper Fuse.js index management
+  - **Implementation approach**:
+    - Create persistent indices instead of rebuilding for each search
+    - Add incremental index updates when items are added/removed
+    - Implement proper index serialization and deserialization
+    - Add option to lazily rebuild indices
+    - Create tests measuring index creation performance
+
+#### 2.2 Implement Basic Caching
+- [ ] Add results caching for repeated queries
+  - **Implementation approach**:
+    - Implement simple Map-based cache for query results
+    - Add cache invalidation on dictionary/object changes
+    - Create configurable cache size limits
+    - Add cache hit/miss tracking for debugging
+    - Implement optional cache persistence
+
+#### 2.3 Add Async Processing for Large Datasets
+- [ ] Implement non-blocking search operations for large datasets
+  - **Implementation approach**:
+    - Create async versions of search methods that don't block main thread
+    - Implement chunked processing for large dictionaries
+    - Add progress tracking for long operations
+    - Create cancellable search operations
+    - Add proper promise handling and error propagation
+    - Measure performance difference between sync and async methods
+
+### 3. API Improvements
+
+#### 3.1 Standardize Method Naming
+- [x] Standardize all method names for consistency
+  - **Implementation completed**:
+    - Renamed `getClosestMatchForString` to `findClosestMatch`
+    - Renamed `getChangeScoreForString` to `calculateScores`
+    - Created backward compatibility aliases with @deprecated tags
+    - Updated all tests with new method names
+    - ✓ Tests pass and build succeeds
+
+#### 3.2 Add Chainable API
+- [ ] Create a more fluent API for complex searches
+  - **Implementation approach**:
+    - Implement chainable methods for setting options
+    - Add result transformation methods (map, filter, sort)
+    - Create fluent search building interface
+    - Implement method chaining for filters and transformations
+    - Add proper TypeScript type inference for chainable methods
+    - Create examples demonstrating the chainable API
+
+#### 3.3 Enhance Return Types
+- [ ] Improve result objects with more useful information
+  - **Implementation approach**:
+    - Standardize return types across all search methods
+    - Add richer match information (character positions, context)
+    - Implement highlighting helpers for match visualization
+    - Add metadata to search results (time taken, options used)
+    - Create proper TypeScript interfaces for all result types
+
+### 4. Documentation and Examples
+
+#### 4.1 Create Comprehensive Documentation
+- [ ] Improve documentation with Fuse.js-specific information
+  - **Implementation approach**:
+    - Generate TypeDoc documentation from JSDoc comments
+    - Create specific sections for Fuse.js integration details
+    - Add visual diagrams showing how Fuse.js is utilized
+    - Document all configuration options with examples
+    - Add performance guidelines based on Fuse.js recommendations
+
+#### 4.2 Create Usage Examples
+- [ ] Add specialized examples for common search patterns
+  - **Implementation approach**:
+    - Create examples for typical search scenarios (autocomplete, filtering, etc.)
+    - Add examples of weighted searching for different use cases
+    - Demonstrate extended search syntax with examples
+    - Create comparative examples showing different configuration effects
+    - Add performance optimization examples
+
+### 5. Testing Enhancements
+
+#### 5.1 Add Fuse.js-specific Tests
+- [ ] Create tests focused on Fuse.js features
+  - **Implementation approach**:
+    - Add tests for all Fuse.js configuration options
+    - Create performance comparison tests for different settings
+    - Implement tests for extended search syntax
+    - Add tests for very large datasets
+    - Create index persistence and rebuilding tests
+
+#### 5.2 Add Edge Case Tests
+- [ ] Improve test coverage for Fuse.js edge cases
+  - **Implementation approach**:
+    - Test with unusual strings (very long, special characters, etc.)
+    - Add tests for multilingual content
+    - Create tests for zero-match and all-match cases
+    - Implement tests for threshold boundary conditions
+    - Add tests for unusual scoring scenarios
+
+## Implementation Priority
+
+### Phase 1: Core Improvements (1-2 weeks)
+- [x] API Improvements (3.1 Standardize Method Naming) ✓ COMPLETED
+- [ ] Configurability Enhancements (1.1 Enhance Configurability)
+- [ ] Documentation Updates (4.1 Create Comprehensive Documentation)
+
+### Phase 2: Performance Optimizations (1-2 weeks)
+- [ ] Optimize Index Creation (2.1)
+- [ ] Implement Basic Caching (2.2)
+- [ ] Add Fuse.js-specific Tests (5.1)
+
+### Phase 3: Advanced Features (2-3 weeks)
+- [ ] Improve Weighted Field Support (1.2)
+- [ ] Add Extended Search Capabilities (1.3)
+- [ ] Add Chainable API (3.2)
+- [ ] Enhance Return Types (3.3)
+- [ ] Add Async Processing for Large Datasets (2.3)
+- [ ] Create Usage Examples (4.2)
+- [ ] Add Edge Case Tests (5.2)
+
+## Expected Outcomes
+- Significantly improved performance for large datasets
+- More flexible and powerful search capabilities
+- Better developer experience with improved API design
+- Clearer understanding of the library through better documentation
+- Higher test coverage, particularly for edge cases and performance scenarios
--- a/test/test.articlesearch.ts
+++ b/test/test.articlesearch.ts
@ -1,34 +1,131 @@
-import { expect, tap } from '@pushrocks/tapbundle';
+import { expect, tap } from '@push.rocks/tapbundle';
 import * as tsclass from '@tsclass/tsclass';
-import * as smartfuzzy from '../ts/index';
+import * as smartfuzzy from '../ts/index.js';

-tap.test('should sort objects', async () => {
-  const articleArray: tsclass.content.IArticle[] = [
-    {
-      title: 'Berlin has a ambivalent history',
-      content: 'it is known that Berlin has an interesting history',
-      author: null,
-      tags: ['city', 'Europe', 'hello'],
-      timestamp: Date.now(),
-      featuredImageUrl: null,
-      url: null,
-    },
-    {
-      title: 'Washington is a great city',
-      content: 'it is known that Washington is one of the greatest cities in the world',
-      author: null,
-      tags: ['city', 'USA', 'hello'],
-      timestamp: Date.now(),
-      featuredImageUrl: null,
-      url: null,
-    },
-  ];
+// Create fixed timestamps for consistent test results
+const timestamp1 = 1620000000000; // May 2021
+const timestamp2 = 1620086400000; // May 2021 + 1 day

-  const testArticleSearch = new smartfuzzy.ArticleSearch(articleArray);
+// Test articles with known content
+const testArticles: tsclass.content.IArticle[] = [
+  {
+    title: 'Berlin has a ambivalent history',
+    content: 'it is known that Berlin has an interesting history',
+    author: null,
+    tags: ['city', 'Europe', 'history', 'travel'],
+    timestamp: timestamp1,
+    featuredImageUrl: null,
+    url: null,
+  },
+  {
+    title: 'Washington is a great city',
+    content: 'it is known that Washington is one of the greatest cities in the world',
+    author: null,
+    tags: ['city', 'USA', 'travel', 'politics'],
+    timestamp: timestamp2,
+    featuredImageUrl: null,
+    url: null,
+  },
+  {
+    title: 'Travel tips for European cities',
+    content: 'Here are some travel tips for European cities including Berlin and Paris',
+    author: null,
+    tags: ['travel', 'Europe', 'tips'],
+    timestamp: timestamp2,
+    featuredImageUrl: null,
+    url: null,
+  }
+];

-  const result = await testArticleSearch.search('USA');
-  console.log(result);
-  console.log(result[0].matches);
+let articleSearch: smartfuzzy.ArticleSearch;
+
+tap.test('should create an ArticleSearch instance', async () => {
+  // Test creation with constructor
+  articleSearch = new smartfuzzy.ArticleSearch(testArticles);
+  expect(articleSearch).toBeInstanceOf(smartfuzzy.ArticleSearch);
+  expect(articleSearch.articles.length).toEqual(testArticles.length);
+
+  // Test empty constructor
+  const emptySearch = new smartfuzzy.ArticleSearch();
+  expect(emptySearch.articles).toBeArray();
+  expect(emptySearch.articles.length).toEqual(0);
 });

-tap.start();
+tap.test('should search by exact tag match', async () => {
+  const result = await articleSearch.search('USA');
+
+  // Should have results
+  expect(result).toBeArray();
+  expect(result.length).toBeGreaterThan(0);
+
+  // First result should be the Washington article (contains USA tag)
+  expect(result[0].item.title).toInclude('Washington');
+
+  // Should include match information
+  expect(result[0].matches).toBeDefined();
+  expect(result[0].matches.length).toBeGreaterThan(0);
+
+  // At least one match should be for the 'USA' tag
+  const tagMatch = result[0].matches.find(m => m.key === 'tags' && m.value === 'USA');
+  expect(tagMatch).toBeDefined();
+});
+
+tap.test('should search by title and content', async () => {
+  // Search for term in the title and content of one article
+  const result = await articleSearch.search('Berlin');
+
+  expect(result.length).toBeGreaterThan(0);
+  expect(result[0].item.title).toInclude('Berlin');
+
+  // The Travel article mentions Berlin in content, so it should be included
+  // but ranked lower
+  const berlinArticleIndex = result.findIndex(r => r.item.title.includes('Berlin'));
+  const travelArticleIndex = result.findIndex(r => r.item.title.includes('Travel'));
+
+  expect(berlinArticleIndex).toBeLessThan(travelArticleIndex);
+});
+
+tap.test('should add articles incrementally', async () => {
+  const newSearch = new smartfuzzy.ArticleSearch();
+  expect(newSearch.articles.length).toEqual(0);
+
+  // Add one article
+  const newArticle: tsclass.content.IArticle = {
+    title: 'New Article',
+    content: 'This is a new article about technology',
+    author: null,
+    tags: ['technology', 'new'],
+    timestamp: Date.now(),
+    featuredImageUrl: null,
+    url: null,
+  };
+
+  newSearch.addArticle(newArticle);
+  expect(newSearch.articles.length).toEqual(1);
+  expect(newSearch.needsUpdate).toBeTrue();
+
+  // Search should update the index
+  const result = await newSearch.search('technology');
+  expect(result.length).toEqual(1);
+  expect(newSearch.needsUpdate).toBeFalse();
+
+  // Add another article and check if updates work
+  const anotherArticle: tsclass.content.IArticle = {
+    title: 'Another Tech Article',
+    content: 'Another article about technology innovations',
+    author: null,
+    tags: ['technology', 'innovation'],
+    timestamp: Date.now(),
+    featuredImageUrl: null,
+    url: null,
+  };
+
+  newSearch.addArticle(anotherArticle);
+  expect(newSearch.needsUpdate).toBeTrue();
+
+  // Search again should now return both articles
+  const newResult = await newSearch.search('technology');
+  expect(newResult.length).toEqual(2);
+});
+
+export default tap.start();
--- a/test/test.objectsorter.ts
+++ b/test/test.objectsorter.ts
@ -1,21 +1,86 @@
-import { expect, tap } from '@pushrocks/tapbundle';
-import * as smartfuzzy from '../ts/index';
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as smartfuzzy from '../ts/index.js';

-tap.test('should sort objects', async () => {
-  class Car {
-    constructor(public brand: string) {}
-  }
+class Car {
+  constructor(public brand: string, public model?: string, public year?: number) {}
+}

-  let testObjectSorter: smartfuzzy.ObjectSorter<Car>;
+const testCars = [
+  new Car('BMW', 'X5', 2022),
+  new Car('Mercedes Benz', 'S-Class', 2021),
+  new Car('Volvo', 'XC90', 2023),
+  new Car('Volkswagen', 'Golf', 2020),
+  new Car('Audi', 'A4', 2022),
+];

-  testObjectSorter = new smartfuzzy.ObjectSorter([
-    new Car('BMW'),
-    new Car('Mercedes Benz'),
-    new Car('Volvo'),
-  ]);
+let objectSorter: smartfuzzy.ObjectSorter<Car>;

-  const result = testObjectSorter.sort('Volvo', ['brand']);
-  console.log(result);
+tap.test('should create an instance of ObjectSorter', async () => {
+  objectSorter = new smartfuzzy.ObjectSorter<Car>(testCars);
+  expect(objectSorter).toBeInstanceOf(smartfuzzy.ObjectSorter);
+  expect(objectSorter.objectDictionary).toEqual(testCars);
+
+  // Test empty constructor
+  const emptyObjectSorter = new smartfuzzy.ObjectSorter<Car>();
+  expect(emptyObjectSorter.objectDictionary).toEqual([]);
 });

-tap.start();
+tap.test('should sort objects by exact brand match', async () => {
+  const result = objectSorter.sort('Volvo', ['brand']);
+
+  // Should return an array of results
+  expect(result).toBeArray();
+  expect(result.length).toBeGreaterThan(0);
+
+  // First result should be the Volvo
+  expect(result[0].item.brand).toEqual('Volvo');
+
+  // Should have expected result structure
+  expect(result[0]).toHaveProperty('item');
+  expect(result[0]).toHaveProperty('refIndex');
+  expect(result[0].refIndex).toBeTypeofNumber();
+
+  // Reference index should match the original array position
+  expect(result[0].refIndex).toEqual(2); // Volvo is at index 2
+});
+
+tap.test('should sort objects by fuzzy brand match', async () => {
+  // "Wolvo" should fuzzy match to "Volvo"
+  const result = objectSorter.sort('Wolvo', ['brand']);
+
+  expect(result.length).toBeGreaterThan(0);
+  expect(result[0].item.brand).toEqual('Volvo');
+});
+
+tap.test('should sort objects by multiple field search', async () => {
+  // Add a car with similar model name but different brand
+  objectSorter = new smartfuzzy.ObjectSorter<Car>([
+    ...testCars,
+    new Car('Toyota', 'X5 Replica', 2020),
+  ]);
+
+  // Search across both brand and model
+  const result = objectSorter.sort('BMW X5', ['brand', 'model']);
+
+  expect(result.length).toBeGreaterThan(0);
+
+  // BMW X5 should be first result
+  expect(result[0].item.brand).toEqual('BMW');
+  expect(result[0].item.model).toEqual('X5');
+
+  // Toyota X5 Replica may be in results depending on threshold
+  // But we shouldn't expect it specifically since results depend on the
+  // fuzzy matching algorithm's threshold setting
+
+  // BMW should be the first result
+  const bmwIndex = result.findIndex(r => r.item.brand === 'BMW');
+  expect(bmwIndex).toEqual(0);
+
+  // If Toyota is in results, it should be ranked lower than BMW
+  const toyotaIndex = result.findIndex(r => r.item.brand === 'Toyota');
+  if (toyotaIndex !== -1) {
+    expect(bmwIndex).toBeLessThan(toyotaIndex);
+  }
+});
+
+export default tap.start();
--- a/test/test.smartfuzzy.ts
+++ b/test/test.smartfuzzy.ts
@ -1,26 +1,69 @@
-import { expect, tap } from '@pushrocks/tapbundle';
-import * as smartfuzzy from '../ts/index';
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as smartfuzzy from '../ts/index.js';

 let testSmartfuzzy: smartfuzzy.Smartfuzzy;
+const testDictionary = [
+  'Sony',
+  'Deutsche Bahn',
+  'Apple Inc.',
+  "Trader Joe's",
+];

 tap.test('should create an instance of Smartfuzzy', async () => {
-  testSmartfuzzy = new smartfuzzy.Smartfuzzy([
-    'Sony',
-    'Deutsche Bahn',
-    'Apple Inc.',
-    "Trader Joe's",
-  ]);
-  expect(testSmartfuzzy).to.be.instanceof(smartfuzzy.Smartfuzzy);
+  testSmartfuzzy = new smartfuzzy.Smartfuzzy(testDictionary);
+  expect(testSmartfuzzy).toBeInstanceOf(smartfuzzy.Smartfuzzy);
+  expect(testSmartfuzzy.dictionary).toEqual(testDictionary);
 });

-tap.test('should compute a score', async () => {
-  const result = testSmartfuzzy.getChangeScoreForString('Apple');
-  console.log(result);
+tap.test('should compute a score for a string against the dictionary', async () => {
+  const result = testSmartfuzzy.calculateScores('Apple');
+
+  // Check that we got a dictionary map back
+  expect(result).toBeTypeOf('object');
+
+  // Check that every dictionary entry has a score
+  for (const word of testDictionary) {
+    expect(result).toHaveProperty(word);
+    expect(result[word]).toBeTypeofNumber();
+  }
+
+  // Check that 'Apple Inc.' has a lower score (better match) for 'Apple' than other entries
+  // The leven distance for 'Apple Inc.' from 'Apple' should be less than that of other entries
+  // We can't predict exact values but we can compare them
+  expect(result['Apple Inc.']).toBeLessThanOrEqual(result['Sony']);
 });

-tap.test('should get closest match', async () => {
-  const result = testSmartfuzzy.getClosestMatchForString('Apple');
-  console.log(result);
+tap.test('should get closest match for a string', async () => {
+  const result = testSmartfuzzy.findClosestMatch('Apple');
+
+  // Should return closest match as string
+  expect(result).toBeTypeofString();
+
+  // Should match the expected closest entry
+  expect(result).toEqual('Apple Inc.');
 });

-tap.start();
+tap.test('should add words to dictionary', async () => {
+  const initialLength = testSmartfuzzy.dictionary.length;
+
+  // Add a single word
+  testSmartfuzzy.addToDictionary('Microsoft');
+  expect(testSmartfuzzy.dictionary.length).toEqual(initialLength + 1);
+  expect(testSmartfuzzy.dictionary).toContain('Microsoft');
+
+  // Add multiple words
+  const additionalWords = ['Google', 'Amazon', 'Facebook'];
+  testSmartfuzzy.addToDictionary(additionalWords);
+  expect(testSmartfuzzy.dictionary.length).toEqual(initialLength + 4);
+  for (const word of additionalWords) {
+    expect(testSmartfuzzy.dictionary).toContain(word);
+  }
+});
+
+tap.test('should handle empty query string', async () => {
+  const result = testSmartfuzzy.findClosestMatch('');
+  // For empty strings, behavior should be defined (either null or a specific result)
+  expect(result).toBeNullOrUndefined();
+});
+
+export default tap.start();
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartfuzzy',
+  version: '1.1.10',
+  description: 'A library for fuzzy matching strings against word dictionaries or arrays, with support for object and article searching.'
+}
--- a/ts/index.ts
+++ b/ts/index.ts
@ -1,3 +1,3 @@
-export * from './smartfuzzy.articlesearch';
-export * from './smartfuzzy.classes.smartfuzzy';
-export * from './smartfuzzy.classes.objectsorter';
+export * from './smartfuzzy.articlesearch.js';
+export * from './smartfuzzy.classes.smartfuzzy.js';
+export * from './smartfuzzy.classes.objectsorter.js';
--- a/ts/smartfuzzy.articlesearch.ts
+++ b/ts/smartfuzzy.articlesearch.ts
@ -1,37 +1,177 @@
-import * as plugins from './smartfuzzy.plugins';
+import * as plugins from './smartfuzzy.plugins.js';

 /**
- * an article search that searches articles in a weighted manner
+ * Type for the search result returned by ArticleSearch
+ */
+export type IArticleSearchResult = {
+  /** The matched article */
+  item: plugins.tsclass.content.IArticle;
+
+  /** The index of the article in the original array */
+  refIndex: number;
+
+  /** The match score (lower is better) */
+  score?: number;
+
+  /** Information about where matches were found in the article */
+  matches?: ReadonlyArray<{
+    indices: ReadonlyArray<readonly [number, number]>;
+    key?: string;
+    value?: string;
+    refIndex?: number;
+  }>;
+}
+
+/**
+ * Specialized search engine for articles with weighted field searching
+ *
+ * This class provides fuzzy searching against article content, with different weights
+ * assigned to different parts of the article (title, tags, content) to provide
+ * more relevant results.
+ *
+ * @example
+ * ```typescript
+ * const articles = [
+ *   {
+ *     title: 'Getting Started with TypeScript',
+ *     content: 'TypeScript is a superset of JavaScript that adds static typing...',
+ *     tags: ['typescript', 'javascript', 'programming'],
+ *     author: 'John Doe',
+ *     timestamp: Date.now(),
+ *     featuredImageUrl: null,
+ *     url: 'https://example.com/typescript-intro'
+ *   }
+ * ];
+ *
+ * const articleSearch = new ArticleSearch(articles);
+ * const results = await articleSearch.search('typescript');
+ * ```
 */
 export class ArticleSearch {
+  /**
+   * Collection of articles to search through
+   */
  public articles: plugins.tsclass.content.IArticle[] = [];
+
+  /**
+   * Flag indicating whether the search index needs to be updated
+   */
  public needsUpdate: boolean = false;

+  /**
+   * Promise manager for async operations
+   */
  private readyDeferred = plugins.smartpromise.defer();
+
+  /**
+   * Fuse.js instance for searching
+   */
  private fuse: plugins.fuseJs<plugins.tsclass.content.IArticle>;

+  /**
+   * Creates a new ArticleSearch instance
+   *
+   * @param articleArrayArg - Optional array of articles to initialize with
+   */
  constructor(articleArrayArg?: plugins.tsclass.content.IArticle[]) {
+    // Validate input if provided
+    if (articleArrayArg !== undefined && !Array.isArray(articleArrayArg)) {
+      throw new Error('Article array must be an array');
+    }
+
    this.fuse = new plugins.fuseJs(this.articles);
    this.readyDeferred.resolve();
+
    if (articleArrayArg) {
      for (const article of articleArrayArg) {
+        // Validate each article has required fields
+        if (!article || typeof article !== 'object') {
+          throw new Error('Each article must be a valid object');
+        }
+
+        // Require at least title field
+        if (!article.title || typeof article.title !== 'string') {
+          throw new Error('Each article must have a title string');
+        }
+
        this.addArticle(article);
      }
    }
  }

  /**
-   * allows adding an article
+   * Adds an article to the collection and marks the index for updating
+   *
+   * @param articleArg - The article to add to the search collection
+   * @returns void
+   *
+   * @example
+   * ```typescript
+   * articleSearch.addArticle({
+   *   title: 'Advanced TypeScript Features',
+   *   content: 'This article covers advanced TypeScript concepts...',
+   *   tags: ['typescript', 'advanced'],
+   *   author: 'Jane Smith',
+   *   timestamp: Date.now(),
+   *   featuredImageUrl: null,
+   *   url: 'https://example.com/advanced-typescript'
+   * });
+   * ```
   */
-  addArticle(articleArg: plugins.tsclass.content.IArticle) {
+  public addArticle(articleArg: plugins.tsclass.content.IArticle): void {
+    if (!articleArg || typeof articleArg !== 'object') {
+      throw new Error('Article must be a valid object');
+    }
+
+    // Require at least title field
+    if (!articleArg.title || typeof articleArg.title !== 'string') {
+      throw new Error('Article must have a title string');
+    }
+
+    // Validate tags if present
+    if (articleArg.tags !== undefined && !Array.isArray(articleArg.tags)) {
+      throw new Error('Article tags must be an array of strings');
+    }
+
    this.articles.push(articleArg);
    this.needsUpdate = true;
  }

  /**
-   * allows searching an article
+   * Performs a weighted fuzzy search across all articles
+   *
+   * The search uses the following weighting:
+   * - Title: 3x importance
+   * - Tags: 2x importance
+   * - Content: 1x importance
+   *
+   * @param searchStringArg - The search query string
+   * @returns Array of articles matched with their relevance score and match details
+   *
+   * @example
+   * ```typescript
+   * // Search for articles about TypeScript
+   * const results = await articleSearch.search('typescript');
+   *
+   * // Access the first (most relevant) result
+   * if (results.length > 0) {
+   *   console.log(results[0].item.title);
+   *
+   *   // See where the match was found
+   *   console.log(results[0].matches);
+   * }
+   * ```
   */
-  public async search(searchStringArg: string) {
+  public async search(searchStringArg: string): Promise<IArticleSearchResult[]> {
+    if (typeof searchStringArg !== 'string') {
+      throw new Error('Search string must be a string');
+    }
+
+    // Empty article collection should return empty results
+    if (this.articles.length === 0) {
+      return [];
+    }
+
    if (this.needsUpdate) {
      const oldDeferred = this.readyDeferred;
      this.readyDeferred = plugins.smartpromise.defer();
--- a/ts/smartfuzzy.classes.objectsorter.ts
+++ b/ts/smartfuzzy.classes.objectsorter.ts
@ -1,18 +1,107 @@
-import * as plugins from './smartfuzzy.plugins';
+import * as plugins from './smartfuzzy.plugins.js';

+/**
+ * Result of a fuzzy search on objects
+ *
+ * @typeParam T - The type of object being searched
+ */
+export interface IFuzzySearchResult<T> {
+  /** The matched object */
+  item: T;
+
+  /** The index of the object in the original array */
+  refIndex: number;
+
+  /** The match score (lower is better) */
+  score?: number;
+}
+
+/**
+ * Handles fuzzy searching and sorting of objects based on their properties
+ *
+ * @typeParam T - The type of objects to search through
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const users = [
+ *   { name: 'John Smith', email: 'john@example.com' },
+ *   { name: 'Jane Doe', email: 'jane@example.com' }
+ * ];
+ *
+ * const sorter = new ObjectSorter<User>(users);
+ * const results = sorter.sort('john', ['name', 'email']);
+ * ```
+ */
 export class ObjectSorter<T> {
+  /**
+   * The collection of objects to search through
+   */
  public objectDictionary: T[];

+  /**
+   * Creates a new ObjectSorter instance
+   *
+   * @param objectDictionaryArg - Array of objects to search through
+   */
  constructor(objectDictionaryArg: T[] = []) {
+    if (objectDictionaryArg !== undefined && !Array.isArray(objectDictionaryArg)) {
+      throw new Error('Object dictionary must be an array');
+    }
    this.objectDictionary = objectDictionaryArg;
  }

-  sort(stringArg: string, objectKeysArg: string[]): plugins.fuseJs.FuseResult<T>[] {
+  /**
+   * Searches and sorts objects based on how well they match the search string
+   * in the specified object properties
+   *
+   * @param stringArg - The search query string
+   * @param objectKeysArg - Array of object property names to search within
+   * @returns Array of results sorted by relevance (best matches first)
+   *
+   * @example
+   * ```typescript
+   * // Search for 'john' in both name and email fields
+   * const results = sorter.sort('john', ['name', 'email']);
+   *
+   * // First result is the best match
+   * console.log(results[0].item.name); // 'John Smith'
+   * ```
+   */
+  public sort(stringArg: string, objectKeysArg: string[]): Array<IFuzzySearchResult<T>> {
+    if (typeof stringArg !== 'string') {
+      throw new Error('Search string must be a string');
+    }
+
+    if (!Array.isArray(objectKeysArg)) {
+      throw new Error('Object keys must be an array');
+    }
+
+    if (objectKeysArg.length === 0) {
+      throw new Error('At least one object key must be provided for searching');
+    }
+
+    // Verify all keys are strings
+    for (const key of objectKeysArg) {
+      if (typeof key !== 'string') {
+        throw new Error('All object keys must be strings');
+      }
+    }
+
+    // Empty dictionary should return empty results instead of error
+    if (this.objectDictionary.length === 0) {
+      return [];
+    }
+
    const fuseOptions = {
      shouldSort: true,
-      threshold: 0.6,
-      location: 0,
-      distance: 100,
+      threshold: 0.6,     // Lower values = more strict matching
+      location: 0,        // Where to start searching in the string
+      distance: 100,      // How far to search in the string
      maxPatternLength: 32,
      minMatchCharLength: 1,
      keys: objectKeysArg,
--- a/ts/smartfuzzy.classes.smartfuzzy.ts
+++ b/ts/smartfuzzy.classes.smartfuzzy.ts
@ -1,32 +1,94 @@
-import * as plugins from './smartfuzzy.plugins';
+import * as plugins from './smartfuzzy.plugins.js';

 export let standardExport = 'Hi there! :) This is an exported string';

+/**
+ * Type representing a dictionary of words mapped to their scores
+ * Lower scores typically indicate better matches
+ */
 export type TDictionaryMap = { [key: string]: number };

+/**
+ * Main class for fuzzy string matching against a dictionary
+ *
+ * @example
+ * ```typescript
+ * const fuzzy = new Smartfuzzy(['apple', 'banana', 'orange']);
+ * const result = fuzzy.findClosestMatch('aple'); // Returns 'apple'
+ * ```
+ */
 export class Smartfuzzy {
-  dictionary: string[];
+  /**
+   * Array of words used for fuzzy matching
+   */
+  public dictionary: string[];
+
+  /**
+   * Creates a new Smartfuzzy instance
+   *
+   * @param dictionary - Initial array of words to use for matching
+   */
  constructor(dictionary: string[]) {
+    if (!Array.isArray(dictionary)) {
+      throw new Error('Dictionary must be an array of strings');
+    }
    this.dictionary = dictionary;
  }

  /**
-   * adds words to the dictionary
-   * @param payloadArg
+   * Adds one or more words to the dictionary
+   *
+   * @param payloadArg - A single word or an array of words to add to the dictionary
+   * @returns void
+   *
+   * @example
+   * ```typescript
+   * fuzzy.addToDictionary('pear');
+   * fuzzy.addToDictionary(['pear', 'grape', 'kiwi']);
+   * ```
   */
-  addToDictionary(payloadArg: string | string[]) {
+  public addToDictionary(payloadArg: string | string[]): void {
+    if (payloadArg === undefined || payloadArg === null) {
+      throw new Error('Input cannot be null or undefined');
+    }
+
    if (Array.isArray(payloadArg)) {
+      // Validate all items in array are strings
+      for (const item of payloadArg) {
+        if (typeof item !== 'string') {
+          throw new Error('All items in array must be strings');
+        }
+      }
      this.dictionary = this.dictionary.concat(payloadArg);
-    } else {
+    } else if (typeof payloadArg === 'string') {
      this.dictionary.push(payloadArg);
+    } else {
+      throw new Error('Input must be a string or an array of strings');
    }
  }

  /**
-   * returns the closest match for a given string
-   * @param stringArg
+   * Calculates the Levenshtein distance (edit distance) between the input string
+   * and each word in the dictionary
+   *
+   * @param stringArg - The string to compare against the dictionary
+   * @returns A dictionary map where keys are words and values are edit distances
+   *
+   * @example
+   * ```typescript
+   * const scores = fuzzy.calculateScores('aple');
+   * // Returns: { 'apple': 1, 'banana': 5, 'orange': 5 }
+   * ```
   */
-  getChangeScoreForString(stringArg: string): TDictionaryMap {
+  public calculateScores(stringArg: string): TDictionaryMap {
+    if (typeof stringArg !== 'string') {
+      throw new Error('Input must be a string');
+    }
+
+    if (this.dictionary.length === 0) {
+      throw new Error('Dictionary is empty');
+    }
+
    const dictionaryMap: TDictionaryMap = {};
    for (const wordArg of this.dictionary) {
      dictionaryMap[wordArg] = plugins.leven(stringArg, wordArg);
@ -34,7 +96,34 @@ export class Smartfuzzy {
    return dictionaryMap;
  }

-  getClosestMatchForString(stringArg: string): string {
+  /**
+   * @deprecated Use calculateScores instead
+   */
+  public getChangeScoreForString(stringArg: string): TDictionaryMap {
+    return this.calculateScores(stringArg);
+  }
+
+  /**
+   * Finds the closest matching word in the dictionary using fuzzy search
+   *
+   * @param stringArg - The string to find a match for
+   * @returns The closest matching word, or null if no match is found or dictionary is empty
+   *
+   * @example
+   * ```typescript
+   * const match = fuzzy.findClosestMatch('oragne');
+   * // Returns: 'orange'
+   * ```
+   */
+  public findClosestMatch(stringArg: string): string {
+    if (typeof stringArg !== 'string') {
+      throw new Error('Input must be a string');
+    }
+
+    if (this.dictionary.length === 0) {
+      return null; // Return null for empty dictionary instead of throwing error
+    }
+
    const fuseDictionary: { name: string }[] = [];
    for (const wordArg of this.dictionary) {
      fuseDictionary.push({
@ -58,4 +147,11 @@ export class Smartfuzzy {
    }
    return closestMatch;
  }
+
+  /**
+   * @deprecated Use findClosestMatch instead
+   */
+  public getClosestMatchForString(stringArg: string): string {
+    return this.findClosestMatch(stringArg);
+  }
 }
--- a/ts/smartfuzzy.plugins.ts
+++ b/ts/smartfuzzy.plugins.ts
@ -1,5 +1,5 @@
 // @pushrocks scope
-import * as smartpromise from '@pushrocks/smartpromise';
+import * as smartpromise from '@push.rocks/smartpromise';

 export { smartpromise };

--- a/tsconfig.json
+++ b/tsconfig.json
@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "exclude": [
+    "dist_*/**/*.d.ts"
+  ]
+}
--- a/tslint.json
+++ b/tslint.json
@ -1,17 +0,0 @@
-{
-  "extends": ["tslint:latest", "tslint-config-prettier"],
-  "rules": {
-    "semicolon": [true, "always"],
-    "no-console": false,
-    "ordered-imports": false,
-    "object-literal-sort-keys": false,
-    "member-ordering": {
-      "options":{
-        "order": [
-          "static-method"
-        ]
-      }
-    }
-  },
-  "defaultSeverity": "warning"
-}
Author	SHA1	Message	Date
Philipp Kunz	afbeb7456f	1.1.10	2025-05-15 08:56:05 +00:00
Philipp Kunz	76926a2170	fix(documentation): Update documentation and migration guide with standardized method names and deprecation notices.	2025-05-15 08:56:05 +00:00
Philipp Kunz	a24a02fc97	1.1.9	2025-05-12 23:23:49 +00:00
Philipp Kunz	d3fd86a1fa	fix(core): Update build scripts, refine testing assertions, and enhance documentation	2025-05-12 23:23:49 +00:00
Philipp Kunz	70a34bf467	1.1.8	2025-05-12 13:42:49 +00:00
Philipp Kunz	45951d2610	fix(tests): Standardize test syntax and update testing dependencies	2025-05-12 13:42:49 +00:00
Philipp Kunz	283703ec78	1.1.7	2025-05-12 13:37:34 +00:00
Philipp Kunz	4fc2eb6ece	fix(build): Fix import paths, update CI workflows and upgrade dependencies for ESM compliance	2025-05-12 13:37:34 +00:00
Philipp Kunz	d647706881	update description	2024-05-29 14:13:18 +02:00
Philipp Kunz	9a6afa4531	update tsconfig	2024-04-14 17:37:33 +02:00
Philipp Kunz	039190e681	update npmextra.json: githost	2024-04-01 21:35:09 +02:00
Philipp Kunz	be02f01959	update npmextra.json: githost	2024-04-01 19:58:18 +02:00
Philipp Kunz	df0930e984	update npmextra.json: githost	2024-03-30 21:47:16 +01:00
Philipp Kunz	753dea9d96	switch to new org scheme	2023-07-11 00:43:02 +02:00
Philipp Kunz	ff512a0284	switch to new org scheme	2023-07-10 02:56:01 +02:00
Philipp Kunz	4eead78c55	1.1.6	2021-10-04 13:43:57 +02:00
Philipp Kunz	fa262af6a4	fix(core): update	2021-10-04 13:43:57 +02:00
Philipp Kunz	58f7458acd	1.1.5	2021-10-03 17:38:36 +02:00