encode-decode-codec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,69 @@
+# encode-decode-codec
+
+Encode/decode helper package powered by [`position-unit-codec`](https://www.npmjs.com/package/position-unit-codec), with additional deterministic shuffling and optional Base64 wrapping.
+
+## Install
+
+```bash
+npm install encode-decode-codec
+```
+
+## Usage (ESM)
+
+```js
+import { encode, decode } from "encode-decode-codec";
+
+const options = {
+  shift: 4,
+  unit: "_u_",
+  interval: 3,
+  shuffleSeed: 99,
+  useBase64: true
+};
+
+const encoded = encode("hello world", options);
+const decoded = decode(encoded, options);
+```
+
+## Usage (CommonJS)
+
+```js
+const { encode, decode } = require("encode-decode-codec");
+
+const options = { shift: 4, unit: "_u_", interval: 3, shuffleSeed: 99 };
+const encoded = encode("hello world", options);
+const decoded = decode(encoded, options);
+```
+
+## API
+
+- `encode(text, options?) => string`
+- `decode(encodedText, options?) => string`
+
+Options:
+
+- `shift` number (forwarded to `position-unit-codec`)
+- `unit` string (forwarded to `position-unit-codec`)
+- `interval` number > 0 (forwarded to `position-unit-codec`)
+- `shuffleSeed` integer (default: `1337`) used for deterministic shuffle/unshuffle
+- `useBase64` boolean (default: `true`) wraps shuffled output with Base64
+
+Use the same options in `decode` that you used in `encode`.
+
+## Publish
+
+1. Update `name`, `repository.url`, and license details in `package.json`.
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Login and publish:
+
+```bash
+npm login
+npm publish --access public
+```
+
+

package/dist/constants.cjs

@@ -0,0 +1 @@
+exports.DEFAULT_SHUFFLE_SEED = 1337;

package/dist/constants.js

@@ -0,0 +1 @@
+export const DEFAULT_SHUFFLE_SEED = 1337;

package/dist/core/codec.cjs

@@ -0,0 +1,27 @@
+const { encode: baseEncode, decode: baseDecode } = require("position-unit-codec");
+const { toBase64, fromBase64 } = require("../utils/base64.cjs");
+const { shuffleText, unshuffleText } = require("../utils/shuffle.cjs");
+const { assertString } = require("../validation/assert.cjs");
+const { normalizeOptions } = require("./options.cjs");
+
+function encodeWithLayers(text, options = {}) {
+  assertString(text, "text");
+
+  const normalized = normalizeOptions(options);
+  const positionEncoded = baseEncode(text, normalized.codecOptions);
+  const shuffled = shuffleText(positionEncoded, normalized.shuffleSeed);
+
+  return normalized.useBase64 ? toBase64(shuffled) : shuffled;
+}
+
+function decodeWithLayers(encodedText, options = {}) {
+  assertString(encodedText, "encodedText");
+
+  const normalized = normalizeOptions(options);
+  const unwrapped = normalized.useBase64 ? fromBase64(encodedText) : encodedText;
+  const unshuffled = unshuffleText(unwrapped, normalized.shuffleSeed);
+
+  return baseDecode(unshuffled, normalized.codecOptions);
+}
+
+module.exports = { encodeWithLayers, decodeWithLayers };

package/dist/core/codec.js

@@ -0,0 +1,25 @@
+import { encode as baseEncode, decode as baseDecode } from "position-unit-codec";
+import { toBase64, fromBase64 } from "../utils/base64.js";
+import { shuffleText, unshuffleText } from "../utils/shuffle.js";
+import { assertString } from "../validation/assert.js";
+import { normalizeOptions } from "./options.js";
+
+export function encodeWithLayers(text, options = {}) {
+  assertString(text, "text");
+
+  const normalized = normalizeOptions(options);
+  const positionEncoded = baseEncode(text, normalized.codecOptions);
+  const shuffled = shuffleText(positionEncoded, normalized.shuffleSeed);
+
+  return normalized.useBase64 ? toBase64(shuffled) : shuffled;
+}
+
+export function decodeWithLayers(encodedText, options = {}) {
+  assertString(encodedText, "encodedText");
+
+  const normalized = normalizeOptions(options);
+  const unwrapped = normalized.useBase64 ? fromBase64(encodedText) : encodedText;
+  const unshuffled = unshuffleText(unwrapped, normalized.shuffleSeed);
+
+  return baseDecode(unshuffled, normalized.codecOptions);
+}

package/dist/core/options.cjs

@@ -0,0 +1,26 @@
+const { DEFAULT_SHUFFLE_SEED } = require("../constants.cjs");
+const { assertOptionsObject } = require("../validation/assert.cjs");
+
+function normalizeOptions(options = {}) {
+  assertOptionsObject(options);
+
+  if (options.shuffleSeed !== undefined && !Number.isInteger(options.shuffleSeed)) {
+    throw new TypeError("options.shuffleSeed must be an integer.");
+  }
+
+  if (options.useBase64 !== undefined && typeof options.useBase64 !== "boolean") {
+    throw new TypeError("options.useBase64 must be a boolean.");
+  }
+
+  return {
+    codecOptions: {
+      shift: options.shift,
+      unit: options.unit,
+      interval: options.interval
+    },
+    shuffleSeed: Number.isInteger(options.shuffleSeed) ? options.shuffleSeed : DEFAULT_SHUFFLE_SEED,
+    useBase64: options.useBase64 !== false
+  };
+}
+
+module.exports = { normalizeOptions };

package/dist/core/options.js

@@ -0,0 +1,24 @@
+import { DEFAULT_SHUFFLE_SEED } from "../constants.js";
+import { assertOptionsObject } from "../validation/assert.js";
+
+export function normalizeOptions(options = {}) {
+  assertOptionsObject(options);
+
+  if (options.shuffleSeed !== undefined && !Number.isInteger(options.shuffleSeed)) {
+    throw new TypeError("options.shuffleSeed must be an integer.");
+  }
+
+  if (options.useBase64 !== undefined && typeof options.useBase64 !== "boolean") {
+    throw new TypeError("options.useBase64 must be a boolean.");
+  }
+
+  return {
+    codecOptions: {
+      shift: options.shift,
+      unit: options.unit,
+      interval: options.interval
+    },
+    shuffleSeed: Number.isInteger(options.shuffleSeed) ? options.shuffleSeed : DEFAULT_SHUFFLE_SEED,
+    useBase64: options.useBase64 !== false
+  };
+}

package/dist/index.cjs

@@ -0,0 +1,11 @@
+const { encodeWithLayers, decodeWithLayers } = require("./core/codec.cjs");
+
+function encode(text, options = {}) {
+  return encodeWithLayers(text, options);
+}
+
+function decode(encodedText, options = {}) {
+  return decodeWithLayers(encodedText, options);
+}
+
+module.exports = { encode, decode, default: { encode, decode } };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type CodecOptions = {
+  shift?: number;
+  unit?: string;
+  interval?: number;
+  shuffleSeed?: number;
+  useBase64?: boolean;
+};
+
+export declare function encode(text: string, options?: CodecOptions): string;
+export declare function decode(encodedText: string, options?: CodecOptions): string;
+
+declare const _default: {
+  encode: typeof encode;
+  decode: typeof decode;
+};
+
+export default _default;

package/dist/index.js

@@ -0,0 +1,12 @@
+import "./types.js";
+import { encodeWithLayers, decodeWithLayers } from "./core/codec.js";
+
+export function encode(text, options = {}) {
+  return encodeWithLayers(text, options);
+}
+
+export function decode(encodedText, options = {}) {
+  return decodeWithLayers(encodedText, options);
+}
+
+export default { encode, decode };

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * @typedef {Object} CodecOptions
+ * @property {number} [shift]
+ * @property {string} [unit]
+ * @property {number} [interval]
+ * @property {number} [shuffleSeed]
+ * @property {boolean} [useBase64]
+ */
+
+export {};

package/dist/utils/base64.cjs

@@ -0,0 +1,9 @@
+function toBase64(value) {
+  return Buffer.from(value, "utf8").toString("base64");
+}
+
+function fromBase64(value) {
+  return Buffer.from(value, "base64").toString("utf8");
+}
+
+module.exports = { toBase64, fromBase64 };

package/dist/utils/base64.js

@@ -0,0 +1,7 @@
+export function toBase64(value) {
+  return Buffer.from(value, "utf8").toString("base64");
+}
+
+export function fromBase64(value) {
+  return Buffer.from(value, "base64").toString("utf8");
+}

package/dist/utils/shuffle.cjs

@@ -0,0 +1,47 @@
+function createSeededRng(seed) {
+  let state = Math.imul(seed ^ 0x9e3779b9, 1597334677) >>> 0;
+  return function next() {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return (state >>> 0) / 4294967296;
+  };
+}
+
+function buildPermutation(length, seed) {
+  const rng = createSeededRng(seed >>> 0);
+  const indexes = Array.from({ length }, (_, i) => i);
+
+  for (let i = indexes.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rng() * (i + 1));
+    const tmp = indexes[i];
+    indexes[i] = indexes[j];
+    indexes[j] = tmp;
+  }
+
+  return indexes;
+}
+
+function shuffleText(input, seed) {
+  if (input.length <= 1) return input;
+
+  const chars = Array.from(input);
+  const permutation = buildPermutation(chars.length, seed);
+  return permutation.map((idx) => chars[idx]).join("");
+}
+
+function unshuffleText(input, seed) {
+  if (input.length <= 1) return input;
+
+  const chars = Array.from(input);
+  const permutation = buildPermutation(chars.length, seed);
+  const restored = new Array(chars.length);
+
+  for (let i = 0; i < permutation.length; i += 1) {
+    restored[permutation[i]] = chars[i];
+  }
+
+  return restored.join("");
+}
+
+module.exports = { shuffleText, unshuffleText };

package/dist/utils/shuffle.js

@@ -0,0 +1,45 @@
+function createSeededRng(seed) {
+  let state = Math.imul(seed ^ 0x9e3779b9, 1597334677) >>> 0;
+  return function next() {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return (state >>> 0) / 4294967296;
+  };
+}
+
+function buildPermutation(length, seed) {
+  const rng = createSeededRng(seed >>> 0);
+  const indexes = Array.from({ length }, (_, i) => i);
+
+  for (let i = indexes.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rng() * (i + 1));
+    const tmp = indexes[i];
+    indexes[i] = indexes[j];
+    indexes[j] = tmp;
+  }
+
+  return indexes;
+}
+
+export function shuffleText(input, seed) {
+  if (input.length <= 1) return input;
+
+  const chars = Array.from(input);
+  const permutation = buildPermutation(chars.length, seed);
+  return permutation.map((idx) => chars[idx]).join("");
+}
+
+export function unshuffleText(input, seed) {
+  if (input.length <= 1) return input;
+
+  const chars = Array.from(input);
+  const permutation = buildPermutation(chars.length, seed);
+  const restored = new Array(chars.length);
+
+  for (let i = 0; i < permutation.length; i += 1) {
+    restored[permutation[i]] = chars[i];
+  }
+
+  return restored.join("");
+}

package/dist/validation/assert.cjs

@@ -0,0 +1,13 @@
+function assertString(value, name) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${name} must be a string.`);
+  }
+}
+
+function assertOptionsObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("options must be an object.");
+  }
+}
+
+module.exports = { assertString, assertOptionsObject };

package/dist/validation/assert.js

@@ -0,0 +1,11 @@
+export function assertString(value, name) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${name} must be a string.`);
+  }
+}
+
+export function assertOptionsObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("options must be an object.");
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "encode-decode-codec",
+  "version": "1.0.0",
+  "description": "Encode/decode helper package powered by position-unit-codec.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node test/run-all.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "encode",
+    "decode",
+    "codec",
+    "position-unit-codec"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/encode-decode-codec.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "position-unit-codec": "^1.0.0"
+  }
+}
+
+