@relax.js/core 1.0.0

package/docs/utilities.md

@@ -0,0 +1,143 @@
+# Utilities
+
+Small helper functions and data structures exported from `relaxjs/utils`.
+
+## generateSequentialId
+
+Generates compact, time-ordered unique identifiers. IDs sort lexicographically in creation order, making them useful for ordered collections and databases.
+
+```typescript
+import { generateSequentialId } from 'relaxjs/utils';
+
+const id = generateSequentialId(1);
+// Returns a Base36 string like 'k2j8m3n5p'
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `baseId` | `number` | Unique identifier for the client/process (0 to 1,048,575) |
+
+Use different `baseId` values for different servers or processes to avoid collisions:
+
+```typescript
+const SERVER_ID = parseInt(process.env.SERVER_ID || '0');
+const orderId = generateSequentialId(SERVER_ID);
+```
+
+### Structure
+
+Each ID encodes 58 bits of data in Base36:
+
+| Bits | Field | Range |
+|------|-------|-------|
+| 30 | Timestamp (seconds since 2025-01-01) | Until ~2059 |
+| 8 | Per-second counter | 256 IDs/second |
+| 20 | Client identifier | ~1M unique sources |
+
+### Time-Sortable
+
+IDs generated later sort after earlier IDs:
+
+```typescript
+const id1 = generateSequentialId(0);
+// ... wait ...
+const id2 = generateSequentialId(0);
+console.log(id1 < id2); // true
+```
+
+### Errors
+
+- Throws if `baseId` is out of range (0 to 1,048,575)
+- Throws if more than 256 IDs are generated in a single second
+- Throws if timestamp exceeds range (after ~2059)
+
+## resolveValue
+
+Safely navigates nested object properties using a path array. Returns `undefined` if any segment is null or missing (no exceptions thrown).
+
+```typescript
+import { resolveValue } from 'relaxjs/utils';
+
+const user = { address: { city: 'Stockholm' } };
+
+resolveValue(['address', 'city'], user);
+// Returns: 'Stockholm'
+
+resolveValue(['address', 'zip'], user);
+// Returns: undefined
+
+// Safe with null values
+const data = { user: null };
+resolveValue(['user', 'name'], data);
+// Returns: undefined (no error)
+```
+
+### Use with Dot-Notation Paths
+
+```typescript
+const path = 'user.profile.avatar'.split('.');
+const avatar = resolveValue(path, context);
+```
+
+## LinkedList
+
+A doubly-linked list with O(1) insertion and removal at both ends.
+
+```typescript
+import { LinkedList } from 'relaxjs/utils';
+
+const list = new LinkedList<string>();
+
+list.addFirst('A');
+list.addLast('B');
+list.addLast('C');
+
+console.log(list.length);      // 3
+console.log(list.firstValue);  // 'A'
+console.log(list.lastValue);   // 'C'
+
+list.removeFirst(); // Returns 'A'
+list.removeLast();  // Returns 'C'
+console.log(list.length);      // 1
+```
+
+### Node Access
+
+Access the internal `Node` wrappers to traverse or remove specific nodes:
+
+```typescript
+let node = list.first;
+while (node) {
+    console.log(node.value);
+    node = node.next;
+}
+
+// Remove a specific node
+const node = list.first;
+node.remove(); // Removes from list and updates length
+```
+
+### API
+
+| Method/Property | Description |
+|-----------------|-------------|
+| `addFirst(value)` | Insert at the beginning |
+| `addLast(value)` | Insert at the end |
+| `removeFirst()` | Remove and return the first value |
+| `removeLast()` | Remove and return the last value |
+| `length` | Number of nodes |
+| `first` | First `Node` (or `undefined`) |
+| `last` | Last `Node` (or `undefined`) |
+| `firstValue` | Value of the first node |
+| `lastValue` | Value of the last node |
+
+### Node Properties
+
+| Property | Description |
+|----------|-------------|
+| `value` | The stored value |
+| `next` | Next node (or `null`) |
+| `prev` | Previous node (or `null`) |
+| `remove()` | Remove this node from the list |

package/package.json

@@ -0,0 +1,93 @@
+{
+    "name": "@relax.js/core",
+    "version": "1.0.0",
+    "description": "Ship faster with less code. Web Component library with routing, forms, DI, templating, and i18n. No virtual DOM, no build magic, no surprise re-renders.",
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "watch": "tsc --watch",
+        "test": "vitest --config ./vitest.config.ts",
+        "test:coverage": "vitest run --coverage",
+        "test:ui": "vitest --ui",
+        "buildOld": "tsc",
+        "build": "tsc --emitDeclarationOnly && node build.js",
+        "yalc:publish": "yalc publish && yalc push",
+        "yalc:watch": "nodemon --ext ts,js,json --exec \"npm run yalc:publish\"",
+        "bp": "npm run build && npm run yalc:publish",
+        "publish:npm": "npm run build && npm publish --access public"
+    },
+    "keywords": [],
+    "author": "",
+    "license": "ISC",
+    "dependencies": {
+        "reflect-metadata": "^0.2.2"
+    },
+    "devDependencies": {
+        "@types/jsdom": "^21.1.7",
+        "@vitest/coverage-v8": "^3.0.5",
+        "esbuild": "^0.25.0",
+        "eslint": "^9.17.0",
+        "jsdom": "^26.1.0",
+        "typescript": "^5.7.3",
+        "vite": "^6.0.7",
+        "vite-plugin-ts": "^1.3.2-1",
+        "vitest": "^3.0.5"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        },
+        "./html": {
+            "types": "./dist/html/index.d.ts",
+            "import": "./dist/html/index.mjs",
+            "require": "./dist/html/index.js"
+        },
+        "./http": {
+            "types": "./dist/http/index.d.ts",
+            "import": "./dist/http/index.mjs",
+            "require": "./dist/http/index.js"
+        },
+        "./forms": {
+            "types": "./dist/forms/index.d.ts",
+            "import": "./dist/forms/index.mjs",
+            "require": "./dist/forms/index.js"
+        },
+        "./routing": {
+            "types": "./dist/routing/index.d.ts",
+            "import": "./dist/routing/index.mjs",
+            "require": "./dist/routing/index.js"
+        },
+        "./i18n": {
+            "types": "./dist/i18n/index.d.ts",
+            "import": "./dist/i18n/index.mjs",
+            "require": "./dist/i18n/index.js"
+        },
+        "./elements": {
+            "types": "./dist/elements/index.d.ts",
+            "import": "./dist/elements/index.mjs",
+            "require": "./dist/elements/index.js"
+        },
+        "./utils": {
+            "types": "./dist/utils/index.d.ts",
+            "import": "./dist/utils/index.mjs",
+            "require": "./dist/utils/index.js"
+        },
+        "./di": {
+            "types": "./dist/di/index.d.ts",
+            "import": "./dist/di/index.mjs",
+            "require": "./dist/di/index.js"
+        },
+        "./collections": {
+            "types": "./dist/collections/Index.d.ts",
+            "import": "./dist/collections/index.mjs",
+            "require": "./dist/collections/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "docs"
+    ]
+}