@owlmeans/basic-ids 0.1.2 → 0.1.4

package/README.md

@@ -1,146 +1,58 @@
-# OwlMeans Basic IDs — Basic ID Generating Libraries
+# @owlmeans/basic-ids
 
-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.
+Utilities for generating cryptographically secure random IDs and UUIDs.
+
+## Overview
+
+- Fixed-length random IDs in Base58 or Base64 encoding
+- UUID v4 generation
+- Used throughout OwlMeans for generating run IDs, listener IDs, and entity identifiers
 
 ## Installation
 
 ```bash
-npm install @owlmeans/basic-ids
+bun add @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
+import { createIdOfLength, createRandomPrefix, uuid } from '@owlmeans/basic-ids'
 
-### IdStyle Enum
+// Generate a 12-character Base58 ID (default encoding)
+const runId = createIdOfLength(12)
 
-Defines the available encoding formats for generated IDs.
+// Generate a random prefix (useful for namespaced IDs)
+const prefix = createRandomPrefix(6)
 
-```typescript
-enum IdStyle {
-  Base58 = 'base58',
-  Base64 = 'base64'
-}
+// Standard UUID v4
+const id = uuid()
 ```
 
-**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.
+With explicit encoding:
 
-**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);
+import { createIdOfLength, IdStyle } from '@owlmeans/basic-ids'
 
-// Generate 8-character Base58 ID
-const id3 = createIdOfLength(8, IdStyle.Base58);
+const base64Id = createIdOfLength(16, IdStyle.Base64)
 ```
 
-**Note:** This function generates `length * 2` random bytes and then truncates the encoded result to the desired length to ensure sufficient entropy.
+## API
 
-### uuid()
+### `createIdOfLength(length?, format?): string`
 
-Generates a standard UUID version 4 (random UUID).
+Returns a random ID of exactly `length` characters (default: 6) in `format` encoding (default: Base58).
 
-**Returns:** `string` - A UUID v4 string in the format `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
+### `createRandomPrefix(length?, format?): string`
 
-**Example:**
-```typescript
-const id = uuid();
-// Example output: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
-```
+Returns a random string encoded from `length` random bytes (default: 6 bytes).
 
-## Use Cases
+### `uuid(): string`
 
-### Authentication Tokens
-```typescript
-// Generate a session prefix
-const sessionPrefix = createRandomPrefix(8, IdStyle.Base58);
+Returns a UUID v4 string.
 
-// Generate a short API key
-const apiKey = createIdOfLength(32, IdStyle.Base64);
-```
+### `IdStyle`
 
-### Resource Identifiers
 ```typescript
-// Generate short resource IDs
-const resourceId = createIdOfLength(10);
-
-// Generate unique request IDs
-const requestId = uuid();
+enum IdStyle { Base58 = 'base58', Base64 = 'base64' }
 ```
-
-### 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/basic-ids",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,9 +21,10 @@
     }
   },
   "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
     "@types/uuid": "^10.0.0",
     "nodemon": "^3.1.11",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.2"
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",

package/tsconfig.json

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