TensuraJS 🌀

TensuraJS is a lightweight experimental library that provides containerized variables with strict type enforcement and mutability rules, along with a simple storage utility wrapper for working with browser localStorage.

It’s designed to feel like working with a custom language runtime, giving you a safer and more controlled way to manage variables and persistence.

✨ Features

• Container System

  • Strongly-typed variable definitions.
  • Support for mutable and immutable variables.
  • Controlled assignment with type checking.
  • Error reporting for invalid assignments.

• Storage API

  • Wrapper around localStorage.
  • Safe store, get, remove, and clear operations.
  • Built-in error handling with optional callbacks.

📦 Installation

npm i tensurajs

Then import in your project:

import { container, storage } from "./tensurajs";

🚀 Usage

🔹 Container

A container acts like a strongly typed variable with mutability rules.

import { container } from "./tensura";

// Immutable container
const age = new container({
  name: "age",
  type: "number",
  value: 18,
  mutable: false,
});

console.log(age.name); // "age"
console.log(age.type); // "number"
console.log(age.value); // 18
console.log(age.mutability); // false

// Throws error if reassigned
try {
  age.assign(25); // ❌ Error: immutable
} catch (err) {
  console.error(err.message);
}

// Mutable container
const username = new container({
  name: "username",
  type: "string",
  value: "Rimuru",
  mutable: true,
});

username.assign("Diablo"); // ✅ works
try {
  username.assign(123); // ❌ TypeError: type mismatch
} catch (err) {
  console.error(err.message);
}

🔹 Storage

Safe wrapper for localStorage with encryption encryption.

import { storage } from "./tensurajs";

// Store data
storage.store({
  key: "user",
  data: { id: 1, name: "Rimuru" },
  onSuccess: () => console.log("Stored successfully"),
});

// Retrieve data
const result = storage.get({ key: "user" });
console.log(result.data); // { id: 1, name: "Rimuru" }

// Remove a key
storage.remove({ key: "user" });

// Clear all keys
storage.clear();

// Each method returns a response object
// {
//   success: true | false,
//   data: ...,
//   error: ... // if any
// }

🔹 Store

A global container manager (state management utility) with optional persistence.

import { store } from "./tensurajs";

// Initialize store
store.init({ persist: true, name: "__my_store__" });

// Add containers
const ageContainer = store.add({
  name: "age",
  type: "number",
  value: 30,
  mutable: true,
});

const usernameContainer = store.add({
  name: "username",
  type: "string",
  value: "Rimuru",
  mutable: true,
});

// Get container
const age = store.get("age");
console.log(age.value); // 30

// Update container value
store.update("age", 35);

// Get all containers
console.log(store.all());

// Clear store
store.clear();

🔹 Cipher

Encrypt and decrypt data using a secret key.

import { cipher } from "./tensurajs";

const secret = "supersecret";

// Encrypt data
const encrypted = cipher.encrypt({
  data: { id: 1, name: "Rimuru" },
  secret,
  onSuccess: (res) => console.log("Encrypted:", res.data),
});

// Decrypt data
const decrypted = cipher.decrypt({
  data: encrypted.data,
  secret,
  onSuccess: (res) => console.log("Decrypted:", res.data),
});

📖 API Reference

Options : Container

| Option | Type | Default | Description | | ------- | ------- | ------- | ----------------------------------------------------------------------- | | name | string | — | Unique variable name (required) | | type | string | "any" | Variable type (string, number, boolean, array, object, any) | | value | any | null | Initial value | | mutable | boolean | true | Whether the variable can be reassigned |

Methods: container

| Method | Parameters | Description | | ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | | .assign(newValue) | newValue | Assign a new value to the container, with type and mutability checks. Throws an error if type mismatches or variable is immutable. |

Options : Storage

| Option | Type | Default | Description | | --------- | -------- | ------- | ------------------------------------------------------ | | key | string | — | Key used to store/retrieve/remove data in localStorage | | data | any | — | Data to store (object, array, string, etc.) | | onSuccess | function | — | Callback function executed on success | | onError | function | — | Callback function executed on error |

Methods: storage

| Method | Parameters | Description | | ----------- | ----------------------------------- | ------------------------------------------------------------------------------- | | .store() | { key, data, onSuccess, onError } | Store data in localStorage. Optionally call onSuccess or onError callbacks. | | .get() | { key, onSuccess, onError } | Retrieve data from localStorage. Returns null if key does not exist. | | .remove() | { key, onSuccess, onError } | Remove a specific key from localStorage. | | .clear() | { onSuccess, onError } | Clear all keys from localStorage. |

Options : Store

| Option | Type | Default | Description | | ------- | ------- | ------------------- | ------------------------------------------- | | persist | boolean | false | Whether store data persists in localStorage | | name | string | "tensura_store" | Optional custom name for localStorage key |

Methods: store

| Method | Parameters | Description | | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------- | | .init() | { persist?, name? } | Initialize the store. Optionally persist to localStorage and define a custom store name. | | .add() | { name, type, value, mutable } | Add a new container to the store. Returns the container instance. | | .get() | name | Retrieve a container by name. Returns null if it doesn’t exist. | | .update() | name, value | Update a container's value with type & mutability checks. | | .clear() | — | Clear all containers from memory and localStorage (if persist enabled). | | .all() | — | Returns an object containing all containers currently in the store. |

Options : Cipher

| Option | Type | Default | Description | | --------- | -------- | ------- | -------------------------------------------------- | | data | any | — | Data to encrypt/decrypt (string/object/array etc.) | | secret | string | — | Secret key used for encryption/decryption | | onSuccess | function | — | Callback executed on success | | onError | function | — | Callback executed on error |

Methods: cipher

| Method | Parameters | Description | | ------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- | | .encrypt() | { data, secret, onSuccess?, onError? } | Encrypts data (string/object) using a secret key. Returns an object with { success, data }. | | .decrypt() | { data, secret, onSuccess?, onError? } | Decrypts previously encrypted data using the secret key. Returns an object with { success, data }. |