@tkeron/tools 0.1.0

package/.github/workflows/npm_deploy.yml

@@ -0,0 +1,28 @@
+name: tools package
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-test-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: "https://registry.npmjs.org/"
+
+      - uses: oven-sh/setup-bun@v2
+
+      - run: |
+          bun i
+          bun test
+
+      - name: Authenticate npm
+        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+
+      - name: Publish to npm
+        run: npm publish --access public

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tkeron
+
+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/bun.lock

@@ -0,0 +1,27 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@tkeron/tools",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.2", "", { "dependencies": { "bun-types": "1.2.2" } }, "sha512-tr74gdku+AEDN5ergNiBnplr7hpDp3V1h7fqI2GcR/rsUaM39jpSeKH0TFibRvU0KwniRx5POgaYnaXbk0hU+w=="],
+
+    "@types/node": ["@types/node@22.13.1", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-jK8uzQlrvXqEU91UxiK5J7pKHyzgnI1Qnl0QDHIgVGuolJhRb9EEl28Cj9b3rGR8B2lhFCtvIm5os8lFnO/1Ew=="],
+
+    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+
+    "bun-types": ["bun-types@1.2.2", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-RCbMH5elr9gjgDGDhkTTugA21XtJAy/9jkKe/G3WR2q17VPGhcquf9Sir6uay9iW+7P/BV0CAHA1XlHXMAVKHg=="],
+
+    "typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
+
+    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+  }
+}

package/changelog.md

@@ -0,0 +1,3 @@
+# v0.1.0
+
+- initial repo with useful tools.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@tkeron/tools",
+  "version": "0.1.0",
+  "description": "Useful JavaScript utilities",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "type": "module",
+  "author": "tkeron",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "utilities",
+    "utils"
+  ],
+  "repository": {
+    "url": "git@github.com:tkeron/tools.git"
+  }
+}

package/readme.md

@@ -0,0 +1,3 @@
+# Tkeron Commands
+
+        Simple package to evaluate cli arguments, with minimun dependencies.

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./random";
+export * from "./stack";

package/src/random.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "bun:test";
+import { rng } from "./random";
+
+describe("testing rng", () => {
+  it("should return the same 10 random numbers for seed=344", () => {
+    const numbers = [...rng(344, 10)];
+    const expected = [
+      88811757, 1786880006, -1901549690, -783089686, 1532981021, 1629592611,
+      102726481, -941665653, -1672827444, -141168747,
+    ];
+    expect(numbers).toEqual(expected);
+  });
+
+  it("should return the same 100 random numbers for seed=158484", () => {
+    const numbers = [...rng(158484, 100)];
+    const expected = [
+      -512132828, 98688842, -15169138, 721513946, -771752345, -397269314,
+      1010577276, -2086534859, -1290576361, -1025237601, 1806465972, 2139370233,
+      -1028051820, 39829281, 1120459388, 1768530271, -183529410, -436067078,
+      -248249548, 1527105597, -1571897668, -960918928, 151404779, -495137626,
+      116267794, 1946452820, 1773133059, -738265980, -1600113581, 1667592070,
+      472076620, -1218993303, 611253364, -2014334716, 1210987907, 1565772620,
+      -1552845967, 787622462, 487465828, -181095051, 283030456, 329010540,
+      -603058444, -1480555620, 1104662757, -1029632768, -2094961536, 2023342296,
+      1356788665, 1536461133, -1659154829, 1852856121, -159388878, 1747745150,
+      125113631, 521001332, 541976517, 169589375, -673644939, -891357762,
+      -1722888502, 1382186657, -1417912518, 872079767, -1764820973, 1885020757,
+      -1776253955, 1304230546, -1891946683, -1331478612, 1032049895,
+      -1526859160, 1840120240, 513620220, -1982733411, 32420044, 689159639,
+      -1954077981, -1800022834, -341018408, -228713757, 290336290, 1170540679,
+      2120828749, -2036773459, 1253342555, 1727989076, 1289914814, -1484935724,
+      1243853399, -1321156605, -2125340477, 343773831, 1669764017, -1881013655,
+      977826430, -1259165731, -517468935, -162314014, 1990733797,
+    ];
+    expect(numbers).toEqual(expected);
+  });
+  it.skip("should return info about series of 98688842", () => {
+    const seed = 98688842;
+    const gen = rng(seed);
+    const info = {
+      seed,
+      period: 0,
+      max: Number.MIN_SAFE_INTEGER,
+      min: Number.MAX_SAFE_INTEGER,
+      minPositive: Number.MAX_SAFE_INTEGER,
+      maxNegative: Number.MIN_SAFE_INTEGER,
+    };
+    while (true) {
+      const num = gen.next().value!;
+
+      if (num > info.max) info.max = num;
+      if (num < info.min) info.min = num;
+
+      if (num > 0 && num < info.minPositive) info.minPositive = num;
+      if (num < 0 && num > info.maxNegative) info.maxNegative = num;
+
+      info.period++;
+
+      if (num === seed) break;
+    }
+
+    console.log(JSON.stringify(info, null, 4));
+
+    expect(info).toEqual({
+      seed: 98688842,
+      period: 1073741822,
+      max: 2147483647,
+      min: -2147483646,
+      minPositive: 1,
+      maxNegative: -4,
+    });
+  });
+  it.skip("should return info about series of numbers...", () => {
+    const seeds = [1, 4, 8];
+    const gens = seeds.map((s) => rng(s));
+    const infos = seeds.map((seed) => ({
+      seed,
+      period: 0,
+      max: Number.MIN_SAFE_INTEGER,
+      min: Number.MAX_SAFE_INTEGER,
+      minPositive: Number.MAX_SAFE_INTEGER,
+      maxNegative: Number.MIN_SAFE_INTEGER,
+    }));
+    let i = 0;
+    while (true) {
+      const info = infos[i];
+      const gen = gens[i];
+      const seed = seeds[i];
+
+      const num = gen.next().value!;
+
+      if (num > info.max) info.max = num;
+      if (num < info.min) info.min = num;
+
+      if (num > 0 && num < info.minPositive) info.minPositive = num;
+      if (num < 0 && num > info.maxNegative) info.maxNegative = num;
+
+      info.period++;
+
+      if (num === seed) break;
+
+      i++;
+      if (i >= seeds.length) i = 0;
+    }
+
+    console.log(JSON.stringify(infos, null, 4));
+
+    expect(infos).toEqual([
+      {
+        seed: 1,
+        period: 1073741822,
+        max: 2147483647,
+        min: -2147483646,
+        minPositive: 1,
+        maxNegative: -4,
+      },
+      {
+        seed: 4,
+        period: 1073741821,
+        max: 2147483647,
+        min: -2147483646,
+        minPositive: 1,
+        maxNegative: -4,
+      },
+      {
+        seed: 8,
+        period: 1073741821,
+        max: 2147483647,
+        min: -2147483646,
+        minPositive: 1,
+        maxNegative: -4,
+      },
+    ]);
+  });
+});

package/src/random.ts

@@ -0,0 +1,11 @@
+export function* rng(seed = 0, limit = 0) {
+  let current = 0;
+  while (true) {
+    seed ^= seed << 13;
+    seed ^= seed >> 17;
+    seed ^= seed << 5;
+    yield seed;
+    if (limit > 0) current++;
+    if (limit > 0 && current >= limit) break;
+  }
+}

package/src/stack.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "bun:test";
+import { getFIFO } from "./stack";
+import { getLIFO } from "./stack";
+
+describe("LIFO stack tests", () => {
+  it("should create an empty lifo stack", () => {
+    const lifo = getLIFO<number>();
+    expect(lifo.length).toBe(0);
+    expect(lifo.current).toBe(null);
+  });
+
+  it("should push an item to the lifo stack", () => {
+    const lifo = getLIFO<number>();
+    lifo.push(1);
+    expect(lifo.length).toBe(1);
+    expect(lifo.current).toBe(1);
+  });
+
+  it("should pop an item from the lifo stack", () => {
+    const lifo = getLIFO<number>();
+    lifo.push(1);
+    expect(lifo.current).toBe(1);
+    expect(lifo.pop()).toBe(1);
+    expect(lifo.length).toBe(0);
+    expect(lifo.current).toBe(null);
+  });
+
+  it("should push multiple items to the lifo stack", () => {
+    const lifo = getLIFO<number>();
+    lifo.push(1);
+    lifo.push(2);
+    lifo.push(3);
+    expect(lifo.length).toBe(3);
+    expect(lifo.current).toBe(3);
+  });
+
+  it("should pop multiple items from the lifo stack", () => {
+    const lifo = getLIFO<number>();
+    lifo.push(1);
+    lifo.push(2);
+    lifo.push(3);
+    expect(lifo.pop()).toBe(3);
+    expect(lifo.pop()).toBe(2);
+    expect(lifo.pop()).toBe(1);
+    expect(lifo.length).toBe(0);
+    expect(lifo.current).toBe(null);
+  });
+
+  it("verify LIFO behavior with direct current modification", () => {
+    const lifo = getLIFO<number>();
+    lifo.push(1);
+    lifo.push(2);
+    lifo.current = 3;
+    expect(lifo.length).toBe(2);
+    expect(lifo.current).toBe(3);
+  });
+});
+
+describe("FIFO stack tests", () => {
+  it("should create an empty fifo stack", () => {
+    const fifo = getFIFO<number>();
+    expect(fifo.length).toBe(0);
+    expect(fifo.current).toBe(null);
+  });
+
+  it("should push an item to the fifo stack", () => {
+    const fifo = getFIFO<number>();
+    fifo.push(1);
+    expect(fifo.length).toBe(1);
+    expect(fifo.current).toBe(1);
+  });
+
+  it("should pop an item from the fifo stack", () => {
+    const fifo = getFIFO<number>();
+    fifo.push(1);
+    expect(fifo.current).toBe(1);
+    expect(fifo.pop()).toBe(1);
+    expect(fifo.length).toBe(0);
+    expect(fifo.current).toBe(null);
+  });
+
+  it("should push multiple items to the fifo stack", () => {
+    const fifo = getFIFO<number>();
+    fifo.push(1);
+    fifo.push(2);
+    fifo.push(3);
+    expect(fifo.length).toBe(3);
+    expect(fifo.current).toBe(1);
+  });
+
+  it("should pop multiple items from the fifo stack", () => {
+    const fifo = getFIFO<number>();
+    fifo.push(1);
+    fifo.push(2);
+    fifo.push(3);
+    expect(fifo.pop()).toBe(1);
+    expect(fifo.pop()).toBe(2);
+    expect(fifo.pop()).toBe(3);
+    expect(fifo.length).toBe(0);
+    expect(fifo.current).toBe(null);
+  });
+});

package/src/stack.ts

@@ -0,0 +1,70 @@
+
+export interface Stack<T> {
+    pop: () => T;
+    push: (item: T) => void;
+    readonly length: number;
+    current: T | null;
+}
+
+/**
+ * Returns a LIFO (Last In First Out) stack.
+ * Same as FILO (First In Last Out) stack.
+ * @returns an empty LIFO stack.
+ */
+export const getLIFO = <T>(): Stack<T> => {
+
+    const _stack: T[] = [];
+
+
+    const stack = <Stack<T>>{
+        pop: () => _stack.pop(),
+        push: (item) => _stack.push(item),
+        length: 0,
+        current: <T><unknown>null
+    };
+
+    Object.defineProperty(stack, "current", {
+        get: () => _stack.length ? _stack[_stack.length - 1] : null,
+        set: (value) => {
+            if (_stack.length) _stack[_stack.length - 1] = value;
+        }
+    });
+
+    Object.defineProperty(stack, "length", {
+        get: () => _stack.length,
+    });
+
+
+    return stack;
+
+
+};
+
+/**
+ * Returns a FIFO (First In First Out) stack
+ * @returns an empty FIFO stack
+ */
+export const getFIFO = <T>(): Stack<T> => {
+
+    const _stack: T[] = [];
+    const stack = <Stack<T>>{
+        pop: () => _stack.shift(),
+        push: (item) => _stack.push(item),
+        length: 0,
+        current: <T><unknown>null
+    };
+
+    Object.defineProperty(stack, "current", {
+        get: () => _stack.length ? _stack[0] : null,
+        set: (value) => {
+            if (_stack.length) _stack[0] = value;
+        }
+    });
+
+    Object.defineProperty(stack, "length", {
+        get: () => _stack.length,
+    });
+
+    return stack;
+
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}