From b6a3a95d51ee26c6c3d9f84c6e7f77274715bef8 Mon Sep 17 00:00:00 2001 From: Breno Salles Date: Sat, 27 Mar 2021 17:36:13 +0000 Subject: [PATCH] feat: Added README.md and update release workflow --- .github/workflows/release.yaml | 23 +++++- README.md | 146 +++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+), 4 deletions(-) create mode 100644 README.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 2a0da33..acaac28 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -10,19 +10,34 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - # Setup .npmrc file to publish to npm - uses: actions/setup-node@v2 with: registry-url: 'https://registry.npmjs.org' - + scope: '@drashland' - name: Install deps run: yarn install - - name: Build run: yarn build - - name: Publish run: yarn publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTOMATION_TOKEN }} + + github: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + # Setup .npmrc file to publish to github + - uses: actions/setup-node@v2 + with: + registry-url: 'https://npm.pkg.github.com' + scope: '@drashland' + - name: Install deps + run: yarn install + - name: Build + run: yarn build + - name: Publish + run: yarn publish --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc5d1e2 --- /dev/null +++ b/README.md @@ -0,0 +1,146 @@ +# Moogle + +An easy way to "Google" your "Map" using search terms. + +The name came from that actually. You G**oogle** a **M**ap, giving you +**Moogle**. + +## Rationale + +Everyone likes `Array`! But they come with a problem... If you want to find a +specific object and you don't know the index where is stored in the array, you +have to iterate over the array to find it, making it a really slow. + +Then let's fix it with a `Map`! Well, it's really fast if you already know the +key, but what if you just know a bit of the key? You have to iterate over all +the keys to find the ones that may match your key. It's a bummer. + +What `Moogle` does if joining the best of both worlds! Making it blazing fast! + +## How It Works + +When `Moogle` is instantiated, it stores the lookup table you provide to it as +its `lookup_table` property. When you add items to your lookup table via +`.addItem()`: + +1. Adds the first argument you provide to `.addItem()` as "search terms" and an + "ID" to its `index` property (a `Map` with search terms and IDs -- the IDs + are mapped to items in the lookup table); and + +2. Adds the second argument you provide to `.addItem()` to the lookup table. + +The search term is what you can search for in the index. If your search term +matches anything in the index, the `IndexService` will take the IDs associated +with the search term and use them to target items in the lookup table. + +For example, if you call `.addItem(["hello"], "world")`, the `index` property +will become the following... + + ``` + ["hello", [0]] + ``` + +...and the lookup table will become the following... + + ``` + [0, "world"] + ``` + +This means you can search for the following strings ... + + ``` + h + he + hel + hell + hello + ``` + +...and they will all match `["hello", [0]]` in the `index` `Map`. The ID in +the `Map` (`0` in this case) is used to target the lookup table via `.get()` -- +returning an item from the lookup table without having to iterate through the +entire lookup table in case it has millions of items. + +You should note that each search is cached, so subsequent searches of the same +search term are 2x (sometimes faster) faster than the first search. + +## Guides + +### Starting + +Moogle works in the browser, Node and Deno! How to do it? + +In the browser: + + ```html + + ``` + +In Node: + + ```javascript + // JavaScript + const Moogle = require("@drashland/moogle"); + const service = new Moogle(); + ``` + + ```typescript + // TypeScript + import { Moogle } from "@drashland/moogle"; + const service = new Moogle(); + ``` + +In Deno: + + ```javascript + // JavaScript + import { Moogle } from "https://deno.land/x/moogle"; + const service = new Moogle(); + ``` + + ```typescript + // TypeScript + import { Moogle } from "https://deno.land/x/moogle"; + const service = new Moogle(); + ``` + +### Creating the Moogle service (using TypeScript) + +1. Instantiate Moogle. + + ```typescript + // Create a simple Moogle that stores values + const service = new Moogle(); + // Create a Moogle that stores a specific value + const service = new Moogle(); + ``` + +2. Add items to your lookup table. + + ```typescript + service.addItem(["hello"], "world"); // adds ["hello", [0]] to the index + service.addItem(["again aga"], "again"); // adds ["again", [1]] and ["aga", [1]] to the index + service.addItem(["hello"], "something"); // changes ["hello", [0]] to ["hello", [0,2]] in the index + ``` + +3. Search your lookup table. + + ```typescript + const results = service.search("hel"); + + console.log(results); + // outputs => Map { + // 0 => { + // id: 0, + // item: "world", + // search_term: "hello", + // search_input: "hel" + // }, + // 2 => { + // id: 2, + // item: "something", + // search_term: "hello", + // search_input: "hel" + // }, + // } + ```