initial commit

Author: RichardMarks

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+node_modules/
+dist/

.npmignore

@@ -0,0 +1 @@
+src/

.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "printWidth": 70,
+  "tabWidth": 2,
+  "trailingComma": "all"
+}

CONTRIBUTORS.md

@@ -0,0 +1 @@
+Richard Marks <[email protected]>

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Richard Marks <[email protected]>
+
+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.

README.md

@@ -0,0 +1,112 @@
+# Optimal ID
+<a id="toc"></a>
+
+## Table of Contents
+
+- [About](#about)
+- [Installation](#installation)
+- [API Reference](#api-reference)
+- [Usage](#usage)
+- [License](#license)
+
+## About
+
+`optimal-id` is a small optimized library that generates an optimized string based id value suitable for nosql database unique keys.
+
+It is based upon the research and works of [Peter Zaitsev](https://www.percona.com/blog/2007/03/13/to-uuid-or-not-to-uuid/) and [Karthik Appigatla](https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/).
+
+Assuming a standard v1 UUID of `"4a6b9f70-b678-11eb-a7b6-032e6afcbc8e"`
+
+This code provides the string `"11ebb6784a6b9f70a7b6032e6afcbc8e"`
+
+- rearranges bytes of timestamp for ordered ids
+- removes separator dash characters because we don't need to waste 4 bytes per id
+- zero third-party dependency libraries for a smaller payload
+
+## Installation
+
+Install the package into your project.
+
+### Using NPM
+
+```bash
+npm install --save optimal-id
+```
+
+### Using Yarn Package Manager
+
+```bash
+yarn add optimal-id
+```
+
+> [Return to Table of Contents](#toc)
+
+## API Reference
+
+- `optimal-id` - module exported from npm package
+  - `optId`- interface exported from module
+    - `generate` - function that returns optimal ids
+      ```typescript
+      optId.generate(numIds?: number): OptimalId[]
+      ```
+  - `OptimalId` - type exported from module if using TypeScript
+
+> [Return to Table of Contents](#toc)
+
+## Usage
+
+### Using JavaScript ES5
+
+```javascript
+var optId = require('optimal-id').optId;
+
+// generate one id
+var id = optId.generate()[0];
+
+// generate multiple ids
+var NUM_IDS_TO_GENERATE = 100;
+var ids = optId.generate(NUM_IDS_TO_GENERATE);
+```
+
+or
+
+### Using JavaScript ECMAScript 2015 or later
+
+```javascript
+const { optId } = require('optimal-id');
+
+// generate one id
+const [id] = optId.generate();
+
+// generate multiple ids
+const NUM_IDS_TO_GENERATE = 100;
+const ids = optId.generate(NUM_IDS_TO_GENERATE);
+```
+
+or
+
+### Using Typescript
+
+```typescript
+import { optId, OptimalId } from 'optimal-id';
+
+// generate one id
+const [id]: OptimalId[] = optId.generate();
+
+// generate multiple ids
+const NUM_IDS_TO_GENERATE = 100;
+const ids: OptimalId[] = optId.generate(NUM_IDS_TO_GENERATE);
+```
+
+> [Return to Table of Contents](#toc)
+## License
+
+This library has been developed by Richard Marks, is copyright 2021, and licensed under the MIT License. 
+
+See [LICENSE.md](./LICENSE.md) for full legal details.
+
+> [Return to Table of Contents](#toc)
+
+----
+
+**This library depends on Node.js being built with support for the `crypto` module.**

jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+};

package.json

@@ -0,0 +1,26 @@
+{
+  "name": "optimal-id",
+  "version": "1.0.0",
+  "description": "generates an optimized string based id value suitable for nosql database unique keys",
+  "main": "dist/main.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RichardMarks/optimal-id.git"
+  },
+  "author": "Richard Marks <[email protected]>",
+  "license": "MIT",
+  "private": false,
+  "devDependencies": {
+    "@types/jest": "^26.0.23",
+    "jest": "^26.6.3",
+    "prettier": "^2.3.0",
+    "ts-jest": "^26.5.6",
+    "typescript": "^4.2.4"
+  },
+  "scripts": {
+    "prepublish": "yarn build",
+    "build": "tsc",
+    "clean": "rm -rf ./dist",
+    "test": "jest --passWithNoTests"
+  }
+}

src/index.spec.ts

@@ -0,0 +1,101 @@
+import { optId } from "./index";
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      toBeDistinct(): R;
+      toMatchPattern(pattern: RegExp): R;
+    }
+  }
+}
+
+beforeAll(() => {
+  expect.extend({
+    toBeDistinct(received) {
+      const pass =
+        Array.isArray(received) &&
+        new Set(received).size === received.length;
+      if (pass) {
+        return {
+          message: () => `expected [${received}] array is unique`,
+          pass: true,
+        };
+      } else {
+        return {
+          message: () =>
+            `expected [${received}] array is not to unique`,
+          pass: false,
+        };
+      }
+    },
+    toMatchPattern(received, pattern: RegExp) {
+      if (typeof received !== "string") {
+        return {
+          message: () => `expected [${received}] is not a string`,
+          pass: false,
+        };
+      }
+      const pass = pattern.test(received);
+      if (pass) {
+        return {
+          message: () =>
+            `expected [${received}] string matches pattern`,
+          pass: true,
+        };
+      } else {
+        return {
+          message: () =>
+            `expected [${received}] string does not match pattern`,
+          pass: false,
+        };
+      }
+    },
+  });
+});
+
+it("exports correct interface", () => {
+  expect(optId).toBeDefined();
+  expect(optId).toHaveProperty("generate");
+});
+
+it("generates an id", () => {
+  expect(optId.generate()).toHaveLength(1);
+});
+
+it("generates an id that is 32 characters in length", () => {
+  const [id] = optId.generate();
+  expect(id).toHaveLength(32);
+});
+
+it("generates an id that only contains valid hex characters", () => {
+  const [id] = optId.generate();
+  expect(id).toMatchPattern(/^[a-f0-9]{32}$/);
+});
+
+it("generates n ids", () => {
+  const ids = optId.generate(10);
+  expect(ids).toHaveLength(10);
+});
+
+it("generates n ids that are unique", () => {
+  const ids = optId.generate(10);
+  expect(ids).toBeDistinct();
+});
+
+it("generates n ids that are in ascending order", () => {
+  const ids = optId.generate(20);
+
+  const sortedIds = [...ids].sort((a, b) => {
+    a = a
+      .match(/[a-f0-9]{0,2}/g)!
+      .reverse()
+      .join("");
+    b = b
+      .match(/[a-f0-9]{0,2}/g)!
+      .reverse()
+      .join("");
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+
+  expect(ids).toStrictEqual(sortedIds);
+});

src/index.ts

@@ -0,0 +1,2 @@
+export type { OptimalId } from "./lib/types";
+export { optId } from "./lib/opt-id";