@owlmeans/basic-ids 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+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.

package/README.md

@@ -0,0 +1,146 @@
+# OwlMeans Basic IDs — Basic ID Generating Libraries
+
+A lightweight TypeScript library for generating various types of random and semi-random identifiers. This package is primarily used by the OwlMeans Authentication Subsystem and provides utilities for creating secure, random prefixes and IDs in different encoding formats.
+
+## Installation
+
+```bash
+npm install @owlmeans/basic-ids
+```
+
+## Usage
+
+```typescript
+import { createRandomPrefix, createIdOfLength, uuid, IdStyle } from '@owlmeans/basic-ids';
+
+// Generate a random prefix (default: 6 bytes, Base58 encoded)
+const prefix = createRandomPrefix();
+
+// Generate a specific length ID
+const shortId = createIdOfLength(8, IdStyle.Base58);
+
+// Generate a UUID v4
+const id = uuid();
+```
+
+## API Reference
+
+### IdStyle Enum
+
+Defines the available encoding formats for generated IDs.
+
+```typescript
+enum IdStyle {
+  Base58 = 'base58',
+  Base64 = 'base64'
+}
+```
+
+**Values:**
+- `Base58`: Uses Base58 encoding (default) - more compact, URL-safe, and avoids ambiguous characters
+- `Base64`: Uses Base64 URL-safe encoding without padding - standard web-safe encoding
+
+### createRandomPrefix(length?, format?)
+
+Creates a random prefix using cryptographically secure random bytes.
+
+**Parameters:**
+- `length` (optional): `number` - Number of random bytes to generate (default: 6)
+- `format` (optional): `IdStyle` - Encoding format (default: `IdStyle.Base58`)
+
+**Returns:** `string` - The encoded random prefix
+
+**Example:**
+```typescript
+// Generate 6-byte Base58 prefix (default)
+const prefix1 = createRandomPrefix();
+
+// Generate 10-byte Base64 prefix
+const prefix2 = createRandomPrefix(10, IdStyle.Base64);
+
+// Generate 4-byte Base58 prefix
+const prefix3 = createRandomPrefix(4, IdStyle.Base58);
+```
+
+### createIdOfLength(length?, format?)
+
+Creates an ID of a specific character length by generating random bytes and truncating the encoded result.
+
+**Parameters:**
+- `length` (optional): `number` - Desired character length of the final ID (default: 6)
+- `format` (optional): `IdStyle` - Encoding format (default: `IdStyle.Base58`)
+
+**Returns:** `string` - The encoded ID trimmed to the specified length
+
+**Example:**
+```typescript
+// Generate 6-character Base58 ID (default)
+const id1 = createIdOfLength();
+
+// Generate 12-character Base64 ID
+const id2 = createIdOfLength(12, IdStyle.Base64);
+
+// Generate 8-character Base58 ID
+const id3 = createIdOfLength(8, IdStyle.Base58);
+```
+
+**Note:** This function generates `length * 2` random bytes and then truncates the encoded result to the desired length to ensure sufficient entropy.
+
+### uuid()
+
+Generates a standard UUID version 4 (random UUID).
+
+**Returns:** `string` - A UUID v4 string in the format `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
+
+**Example:**
+```typescript
+const id = uuid();
+// Example output: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+```
+
+## Use Cases
+
+### Authentication Tokens
+```typescript
+// Generate a session prefix
+const sessionPrefix = createRandomPrefix(8, IdStyle.Base58);
+
+// Generate a short API key
+const apiKey = createIdOfLength(32, IdStyle.Base64);
+```
+
+### Resource Identifiers
+```typescript
+// Generate short resource IDs
+const resourceId = createIdOfLength(10);
+
+// Generate unique request IDs
+const requestId = uuid();
+```
+
+### Database Keys
+```typescript
+// Generate compact database keys
+const dbKey = createRandomPrefix(12, IdStyle.Base58);
+```
+
+## Security Considerations
+
+- All random functions use cryptographically secure random number generation via `@noble/hashes`
+- Base58 encoding avoids ambiguous characters (0, O, l, I) making IDs more user-friendly
+- Base64 encoding provides standard web-safe encoding
+- The `createIdOfLength` function generates extra entropy to compensate for truncation
+
+## Dependencies
+
+- `@noble/hashes` - Cryptographic hashing and random number generation
+- `@scure/base` - Base encoding utilities (Base58, Base64)
+- `uuid` - UUID generation
+
+## Part of OwlMeans Common
+
+This package is part of the OwlMeans Common library ecosystem. For more information about the overall architecture and concepts, see the [main README](../../README.md).
+
+## License
+
+See the [LICENSE](../../LICENSE) file in the root directory.

package/build/consts.d.ts

@@ -0,0 +1,5 @@
+export declare enum IdStyle {
+    Base58 = "base58",
+    Base64 = "base64"
+}
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,oBAAY,OAAO;IACjB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB"}

package/build/consts.js

@@ -0,0 +1,6 @@
+export var IdStyle;
+(function (IdStyle) {
+    IdStyle["Base58"] = "base58";
+    IdStyle["Base64"] = "base64";
+})(IdStyle || (IdStyle = {}));
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,OAGX;AAHD,WAAY,OAAO;IACjB,4BAAiB,CAAA;IACjB,4BAAiB,CAAA;AACnB,CAAC,EAHW,OAAO,KAAP,OAAO,QAGlB"}

package/build/helper.d.ts

@@ -0,0 +1,5 @@
+import { IdStyle } from './consts.js';
+export declare const createRandomPrefix: (length?: number, format?: IdStyle) => string;
+export declare const createIdOfLength: (length?: number, format?: IdStyle) => string;
+export declare const uuid: () => string;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAGrC,eAAO,MAAM,kBAAkB,YAAY,MAAM,WAAc,OAAO,KAAoB,MASzF,CAAA;AAED,eAAO,MAAM,gBAAgB,YAAY,MAAM,WAAc,OAAO,KAAoB,MAEvF,CAAA;AAED,eAAO,MAAM,IAAI,QAAO,MAAc,CAAA"}

package/build/helper.js

@@ -0,0 +1,19 @@
+import { randomBytes } from '@noble/hashes/utils';
+import { base58, base64urlnopad } from '@scure/base';
+import { IdStyle } from './consts.js';
+import { v4 } from 'uuid';
+export const createRandomPrefix = (length = 6, format = IdStyle.Base58) => {
+    const rand = randomBytes(length);
+    switch (format) {
+        case IdStyle.Base64:
+            return base64urlnopad.encode(rand);
+        case IdStyle.Base58:
+        default:
+            return base58.encode(rand);
+    }
+};
+export const createIdOfLength = (length = 6, format = IdStyle.Base58) => {
+    return createRandomPrefix(length * 2, format).slice(0, length);
+};
+export const uuid = () => v4();
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAA;AAEzB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAiB,CAAC,EAAE,SAAkB,OAAO,CAAC,MAAM,EAAU,EAAE;IACjG,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;IAChC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO,CAAC,MAAM;YACjB,OAAO,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACpC,KAAK,OAAO,CAAC,MAAM,CAAC;QACpB;YACE,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,SAAiB,CAAC,EAAE,SAAkB,OAAO,CAAC,MAAM,EAAU,EAAE;IAC/F,OAAO,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AAChE,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,GAAW,EAAE,CAAC,EAAE,EAAE,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export * from './helper.js';
+export * from './consts.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './helper.js';
+export * from './consts.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@owlmeans/basic-ids",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 42 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/uuid": "^10.0.0",
+    "nodemon": "^3.1.7",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.5.0",
+    "@scure/base": "^1.1.9",
+    "uuid": "^10.0.0"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,5 @@
+
+export enum IdStyle {
+  Base58 = 'base58',
+  Base64 = 'base64'
+}

package/src/helper.ts

@@ -0,0 +1,22 @@
+
+import { randomBytes } from '@noble/hashes/utils'
+import { base58, base64urlnopad } from '@scure/base'
+import { IdStyle } from './consts.js'
+import { v4 } from 'uuid'
+
+export const createRandomPrefix = (length: number = 6, format: IdStyle = IdStyle.Base58): string => {
+  const rand = randomBytes(length)
+  switch (format) {
+    case IdStyle.Base64:
+      return base64urlnopad.encode(rand)
+    case IdStyle.Base58:
+    default:
+      return base58.encode(rand)
+  }
+}
+
+export const createIdOfLength = (length: number = 6, format: IdStyle = IdStyle.Base58): string => {
+  return createRandomPrefix(length * 2, format).slice(0, length)
+}
+
+export const uuid = (): string => v4()

package/src/index.ts

@@ -0,0 +1,3 @@
+
+export * from './helper.js'
+export * from './consts.js'

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": [
+    "../tsconfig.default.json",
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/consts.ts","./src/helper.ts","./src/index.ts"],"version":"5.6.3"}