crudjt 1.0.0-beta.0

package/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: crudjt # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/workflows/build.yml

@@ -0,0 +1,42 @@
+name: Build and Test Node.js Library
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            arch: x86_64
+          - os: macos-latest
+            arch: aarch64
+          - os: windows-latest
+            arch: x86_64
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: |
+          npm install
+          npm run cargo-build -- --release
+
+      - name: Create package 'crudjt'
+        run: npm pack
+
+      - name: Run Node.js test
+        env:
+          CRUDJT_AUTOTEST_ALLOWED: true
+        working-directory: ./test-neon-package
+        run: |
+          npm install ../crudjt-1.0.0-beta.0.tgz
+          node test.js

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+- Docker support
+- Performance metrics
+- Disk footprint
+
+## [1.0.0-beta.0] - 2026-03-18
+- Initial beta release
+- Fast B-tree–backed token store for stateful user sessions
+- Provides authentication and authorization across multiple processes
+- Optimized for vertical scaling on a single server

package/Cache.js

@@ -0,0 +1,82 @@
+// This binding was generated automatically to ensure consistency across languages
+// Generated using ChatGPT (GPT-5) from the canonical Ruby SDK
+// API is stable and production-ready
+
+const { LRUCache } = require('lru-cache')
+const CACHE_CAPACITY = 40_000;
+
+class Cache {
+  constructor(readFunc) {
+    this.cache = new LRUCache({
+      max: CACHE_CAPACITY,
+      updateAgeOnGet: true,
+    });
+    this.readFunc = readFunc;
+  }
+
+  get(token) {
+    let cachedValue = this.cache.get(token);
+
+    if (cachedValue) {
+      this.cache.set(token, cachedValue);
+
+      const output = {};
+      const metadata = cachedValue['metadata'] || {};
+
+      if (metadata['ttl']) {
+        const ttl = Math.ceil((new Date(metadata['ttl']).getTime() - Date.now()) / 1000);
+        if (ttl <= 0) {
+          this.cache.delete(token);
+          return;
+        }
+        output['metadata'] = { ttl };
+      }
+
+      let silence_read = undefined;
+      if (cachedValue['metadata']) {
+        if (cachedValue['metadata']['silence_read']) {
+          silence_read = cachedValue['metadata']['silence_read'];
+        }
+      }
+
+      if (silence_read) {
+        silence_read = (cachedValue['metadata']['silence_read'] -= 1)
+        output['metadata'] ||= {};
+        output['metadata']['silence_read'] = silence_read;
+
+        if (silence_read <= 0) {
+          this.cache.delete(token);
+        }
+
+        this.readFunc(token);
+      }
+
+      output['data'] = cachedValue['data'];
+      return output;
+    }
+  }
+
+  insert(key, token, ttl, silence_read) {
+    const hash = { data: token, metadata: {} };
+
+    if (ttl > 0) {
+      hash['metadata']['ttl'] = new Date(Date.now() + ttl * 1000).toISOString();
+    }
+
+    if (silence_read > 0) {
+      hash['metadata']['silence_read'] = silence_read;
+    }
+
+    this.cache.set(key, hash);
+  }
+
+  forceInsert(token, hash) {
+    this.cache.set(token, hash);
+  }
+
+  delete(token) {
+    this.cache.delete(token);
+  }
+}
+
+module.exports = Cache;

package/Cargo.lock

@@ -0,0 +1,176 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "crudjt"
+version = "1.0.0-beta.0"
+dependencies = [
+ "lazy_static",
+ "libloading",
+ "neon",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "getrandom"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.177"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2874a2af47a2325c2001a6e6fad9b16a53b802102b528163885171cf92b15976"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "linkme"
+version = "0.3.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e3283ed2d0e50c06dd8602e0ab319bb048b6325d0bba739db64ed8205179898"
+dependencies = [
+ "linkme-impl",
+]
+
+[[package]]
+name = "linkme-impl"
+version = "0.3.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5cec0ec4228b4853bb129c84dbf093a27e6c7a20526da046defc334a1b017f7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "neon"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74c1d298c79e60a3f5a1e638ace1f9c1229d2a97bd3a9e40a63b67c8efa0f1e1"
+dependencies = [
+ "either",
+ "getrandom",
+ "libloading",
+ "linkme",
+ "neon-macros",
+ "once_cell",
+ "semver",
+ "send_wrapper",
+ "smallvec",
+]
+
+[[package]]
+name = "neon-macros"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c39e43767817fc963f90f400600967a2b2403602c6440685d09a6bc4e02b70b1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ee95bc4ef87b8d5ba32e8b7714ccc834865276eab0aed5c9958d00ec45f49e8"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.41"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce25767e7b499d1b604768e7cde645d14cc8584231ea6b295e9c9eb22c02e1d1"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d767eb0aabc880b29956c35734170f26ed551a859dbd361d140cdbeca61ab1e2"
+
+[[package]]
+name = "send_wrapper"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
+
+[[package]]
+name = "smallvec"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+
+[[package]]
+name = "syn"
+version = "2.0.108"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da58917d35242480a05c2897064da0a80589a2a0476c9a3f2fdc83b53502e917"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "462eeb75aeb73aea900253ce739c8e18a67423fadf006037cd3ff27e82748a06"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

package/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "crudjt"
+version = "1.0.0-beta.0"
+license = "MIT"
+edition = "2021"
+exclude = ["index.node"]
+
+[lib]
+crate-type = ["cdylib"]
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+lazy_static = "1.5.0"
+libloading = "0.8.5"
+neon = "1"

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 v_akymov
+
+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,215 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="logos/crudjt_logo_white_on_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="logos/crudjt_logo_dark_on_white.svg">
+    <img alt="Shows a dark logo" src="logos/crudjt_logo_dark.png">
+  </picture>
+    </br>
+    JavaScript SDK for the fast, file-backed, scalable JSON token engine
+</p>
+
+<p align="center">
+  <a href="https://www.patreon.com/crudjt">
+    <img src="logos/buy_me_a_coffee_orange.svg" alt="Buy Me a Coffee"/>
+  </a>
+</p>
+
+> ⚠️ Version 1.0.0-beta — production testing phase   
+> API is stable. Feedback is welcome before the final 1.0.0 release
+
+Fast B-tree–backed token store for stateful user sessions  
+Provides authentication and authorization across multiple processes  
+Optimized for vertical scaling on a single server
+
+# Installation
+
+##### NPM or (Yarn)
+
+```sh
+npm install crudjt
+```
+
+## How to use
+
+- One process starts the master
+- All other processes connect to it
+
+## Start CRUDJT master (once)
+
+Start the CRUDJT master when your application boots  
+
+Only **one process** should do this  
+
+The master is responsible for session state and coordination  
+All functions can also be used directly from it
+
+### Generate a new secret key (terminal)
+
+```sh
+export CRUDJT_SECRET_KEY=$(openssl rand -base64 48)
+```
+
+### Start master (JavaScript)
+
+```javascript
+const CRUDJT = require('crudjt');
+
+await CRUDJT.Config.startMaster({
+  secret_key: process.env.CRUDJT_SECRET_KEY,
+  store_jt_path: 'path/to/local/storage', // optional
+  grpc_host: '127.0.0.1', // default
+  grpc_port: 50051 // default
+});
+
+// Use await CRUDJT.Config.shutdownServer() to shut down the gRPC server and let
+// the process exit
+```
+
+*Important: Use the same `secret_key` across all sessions. If the key changes, previously stored tokens cannot be decrypted and will return `null` or `false`*  
+
+## Connect to an existing CRUDJT master
+
+Use this in all other processes  
+
+Typical examples:
+- multiple local processes
+- background jobs
+- forked processes
+
+```javascript
+const CRUDJT = require('crudjt');
+
+CRUDJT.Config.connectToMaster({
+  grpc_host: '127.0.0.1', // default
+  grpc_port: 50051 // default
+});
+```
+
+### Process layout
+
+App boot  
+ ├─ Process A → start_master  
+ ├─ Process B → connect_to_master  
+ └─ Process C → connect_to_master  
+
+# C
+
+```javascript
+const data = { user_id: 42, role: 11 }; // required
+const ttl = 3600 * 24 * 30; // optional: token lifetime (seconds)
+
+// Optional: read limit
+// Each read decrements the counter
+// When it reaches zero — the token is deleted
+const silenceRead = 10;
+
+const token = await CRUDJT.create(data, ttl, silenceRead);
+// token === 'HBmKFXoXgJ46mCqer1WXyQ'
+```
+
+```javascript
+// To disable token expiration or read limits, pass `null`
+const token = await CRUDJT.create(
+  { user_id: 42, role: 11 },
+  null, // disable TTL
+  null  // disable read limit
+);
+```
+
+# R
+
+```javascript
+const result = await CRUDJT.read('HBmKFXoXgJ46mCqer1WXyQ');
+// result === { metadata: { ttl: 101001, silence_read: 9 }, data: { user_id: 42, role: 11 } }
+```
+
+```javascript
+// When expired or not found token
+const result = await CRUDJT.read('HBmKFXoXgJ46mCqer1WXyQ');
+// result === null
+```
+
+# U
+
+```javascript
+const data = { user_id: 42, role: 8 };
+
+// `null` disables limits
+const ttl = 600;
+const silenceRead = 100;
+
+const result = await CRUDJT.update('HBmKFXoXgJ46mCqer1WXyQ', data, ttl, silenceRead);
+// result === true
+```
+
+```javascript
+// When expired or not found token
+const result = await CRUDJT.update('HBmKFXoXgJ46mCqer1WXyQ', { user_id: 42, role: 8 });
+// result === false
+```
+
+# D
+```javascript
+const result = await CRUDJT.delete('HBmKFXoXgJ46mCqer1WXyQ');
+// result === true
+```
+
+```javascript
+// When expired or not found token
+const result = await CRUDJT.delete('HBmKFXoXgJ46mCqer1WXyQ');
+// result === false
+```
+
+# Performance
+> Metrics will be published after 1.0.0-beta GitHub Actions builds
+
+# Storage (File-backed)  
+
+## Disk footprint  
+> Metrics will be published after 1.0.0-beta GitHub Actions builds
+
+## Path Lookup Order
+Stored tokens are placed in the **file system** according to the following order
+
+1. Explicitly set via `CRUDJT.Config.startMaster({store_jt_path: 'custom/path/to/file_system_db'});`
+2. Default system location
+   - **Linux**: `/var/lib/store_jt`
+   - **macOS**: `/usr/local/var/store_jt`
+   - **Windows**: `C:\Program Files\store_jt`
+3. Project root directory (fallback)
+
+## Storage Characteristics
+* CRUDJT **automatically removing expired tokens** after start and every 24 hours without blocking the main thread   
+* **Storage automatically fsyncs every 500ms**, meanwhile tokens ​​are available from cache
+
+# Multi-process Coordination
+For multi-process scenarios, CRUDJT uses gRPC over an insecure local port for same-host communication only. It is not intended for inter-machine or internet-facing usage
+
+# Limits
+The library has the following limits and requirements
+
+- **Node version:** >= 18.0.0
+- **Supported platforms:** Linux, macOS, Windows (x86_64 / arm64)
+- **Maximum json size per token:** 256 bytes
+- **`secret_key` format:** must be Base64
+- **`secret_key` size:** must be 32, 48, or 64 bytes
+
+# Contact & Support
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="logos/crudjt_favicon_160x160_white_on_dark.svg" width=160 height=160>
+    <source media="(prefers-color-scheme: light)" srcset="logos/crudjt_favicon_160x160_dark_on_white.svg" width=160 height=160>
+    <img alt="Shows a dark favicon in light color mode and a white one in dark color mode" src="logos/crudjt_favicon_160x160_white.png" width=160 height=160>
+  </picture>
+</p>
+
+- **Custom integrations / new features / collaboration**: support@crudjt.com  
+- **Library support & bug reports:** [open an issue](https://github.com/crudjt/crudjt-javascript/issues)
+
+
+# License
+CRUDJT is released under the [MIT License](LICENSE.txt)
+
+<p align="center">
+  💘 Shoot your g . ? Love me out via <a href="https://www.patreon.com/crudjt">Patreon Sponsors</a>!
+</p>