@serum-enterprises/json 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Serum Enterprises L.L.C-FZ
+
+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,60 @@
+# JSON
+
+Type-Safe drop-in replacement for the native JSON Object
+
+## Installation
+
+```bash
+npm install --save @serum-enterprises/json
+```
+
+## Usage
+
+```typescript
+import * as JSON from '@serum-enterprises/json';
+
+const data: JSON.JSON = { name: 'John Doe', age: 25 };
+
+function verify(data: JSON.JSON): boolean {
+	if(!JSON.isObject(data))
+		return false;
+
+	if(!JSON.isString(data.name) || !JSON.isInteger(data.age))
+		return false;
+
+	return true;
+}
+
+if(verify(data)) {
+	console.log(`Data is correct: `);
+	console.log(JSON.stringify(data, null, 2));
+}
+```
+
+## API
+
+Please check [JSON.d.ts](./types/JSON.d.ts) for the full API.
+
+## LICENSE
+
+MIT License
+
+Copyright (c) 2025 Serum Enterprises L.L.C-FZ
+
+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/build/JSON.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNull = isNull;
+exports.isBoolean = isBoolean;
+exports.isNumber = isNumber;
+exports.isInteger = isInteger;
+exports.isString = isString;
+exports.isShallowArray = isShallowArray;
+exports.isArray = isArray;
+exports.isShallowObject = isShallowObject;
+exports.isObject = isObject;
+exports.isPrimitive = isPrimitive;
+exports.isShallowContainer = isShallowContainer;
+exports.isContainer = isContainer;
+exports.isShallowJSON = isShallowJSON;
+exports.isJSON = isJSON;
+exports.clone = clone;
+exports.parse = parse;
+exports.stringify = stringify;
+function isNull(value) {
+    return value === null;
+}
+function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+function isNumber(value) {
+    // Using Number.isFinite here as NaN, Infinity and -Infinity are not valid JSON Numbers
+    return Number.isFinite(value);
+}
+function isInteger(value) {
+    // Using Number.isSafeInteger here as JS Numbers are 64-bit floating point numbers and not all integers can be represented accurately
+    return Number.isSafeInteger(value);
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+function isShallowArray(value) {
+    return Array.isArray(value);
+}
+function isArray(value) {
+    return isShallowArray(value) && value.every((v) => isJSON(v));
+}
+function isShallowObject(value) {
+    // Using Object.prototype.toString.call here as it is the most reliable way to check if something is an Object
+    return (Object.prototype.toString.call(value) === '[object Object]');
+}
+function isObject(value) {
+    return isShallowObject(value) && Object.values(value).every((v) => isJSON(v));
+}
+function isPrimitive(value) {
+    return isBoolean(value) || isNumber(value) || isString(value);
+}
+function isShallowContainer(value) {
+    return isShallowArray(value) || isShallowObject(value);
+}
+function isContainer(value) {
+    return isArray(value) || isObject(value);
+}
+function isShallowJSON(value) {
+    return isNull(value) || isPrimitive(value) || isShallowArray(value) || isShallowObject(value);
+}
+function isJSON(value) {
+    return isNull(value) || isPrimitive(value) || isContainer(value);
+}
+function clone(value) {
+    // Using Shallow Checks here as it is expected that value is JSON anyway, and this function is recursive anyway
+    if (isShallowObject(value))
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, clone(v)]));
+    else if (isShallowArray(value))
+        return value.map((v) => clone(v));
+    else
+        return value;
+}
+// Compatibility Method for the native JSON.parse
+function parse(value) {
+    return globalThis.JSON.parse(value);
+}
+// Compatibility Method for the native JSON.stringify
+function stringify(value) {
+    return globalThis.JSON.stringify(value);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@serum-enterprises/json",
+	"version": "2.0.1",
+	"engines": {
+		"node": ">=14.0.0"
+	},
+	"description": "Type-Safe drop-in replacement for the native JSON Object",
+	"main": "./build/JSON.js",
+	"types": "./types/JSON.d.ts",
+	"scripts": {
+		"build": "tsc",
+		"test": "jest"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Serum-Enterprises/SerumJS.git"
+	},
+	"author": "Philipp Steckenbauer <philipp@serum.enterprises>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/Serum-Enterprises/SerumJS/issues"
+	},
+	"devDependencies": {
+		"@types/jest": "^29.5.14",
+		"@types/node": "^22.10.5",
+		"jest": "^29.7.0",
+		"typescript": "^5.7.3"
+	}
+}

package/src/JSON.ts

@@ -0,0 +1,91 @@
+export type Null = null;
+export type Boolean = boolean;
+export type Number = number;
+export type Integer = number;
+export type String = string;
+export type Array = JSON[];
+export type ShallowArray = unknown[];
+export type Object = { [key: string]: JSON };
+export type ShallowObject = { [key: string]: unknown };
+export type Primitive = Boolean | Number | String;
+export type Container = Array | Object;
+export type JSON = Null | Primitive | Container;
+
+export function isNull(value: unknown): value is Null {
+	return value === null;
+}
+
+export function isBoolean(value: unknown): value is Boolean {
+	return typeof value === 'boolean';
+}
+
+export function isNumber(value: unknown): value is Number {
+	// Using Number.isFinite here as NaN, Infinity and -Infinity are not valid JSON Numbers
+	return Number.isFinite(value);
+}
+
+export function isInteger(value: unknown): value is Integer {
+	// Using Number.isSafeInteger here as JS Numbers are 64-bit floating point numbers and not all integers can be represented accurately
+	return Number.isSafeInteger(value);
+}
+
+export function isString(value: unknown): value is String {
+	return typeof value === 'string';
+}
+
+export function isShallowArray(value: unknown): value is ShallowArray {
+	return Array.isArray(value);
+}
+
+export function isArray(value: unknown): value is Array {
+	return isShallowArray(value) && value.every((v) => isJSON(v));
+}
+
+export function isShallowObject(value: unknown): value is ShallowObject {
+	// Using Object.prototype.toString.call here as it is the most reliable way to check if something is an Object
+	return (Object.prototype.toString.call(value) === '[object Object]');
+}
+
+export function isObject(value: unknown): value is Object {
+	return isShallowObject(value) && Object.values(value).every((v) => isJSON(v));
+}
+
+export function isPrimitive(value: unknown): value is Primitive {
+	return isBoolean(value) || isNumber(value) || isString(value);
+}
+
+export function isShallowContainer(value: unknown): value is unknown[] | { [key: string]: unknown } {
+	return isShallowArray(value) || isShallowObject(value);
+}
+
+export function isContainer(value: unknown): value is Container {
+	return isArray(value) || isObject(value);
+}
+
+export function isShallowJSON(value: unknown): value is Null | Boolean | Number | String | unknown[] | { [key: string]: unknown } {
+	return isNull(value) || isPrimitive(value) || isShallowArray(value) || isShallowObject(value);
+}
+
+export function isJSON(value: unknown): value is JSON {
+	return isNull(value) || isPrimitive(value) || isContainer(value);
+}
+
+export function clone<T extends JSON = JSON>(value: T): T {
+	// Using Shallow Checks here as it is expected that value is JSON anyway, and this function is recursive anyway
+	if (isShallowObject(value))
+		return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, clone(v as JSON)])) as T;
+	else if (isShallowArray(value))
+		return value.map((v) => clone(v)) as T;
+	else
+		return value;
+}
+
+// Compatibility Method for the native JSON.parse
+export function parse(value: string): JSON {
+	return globalThis.JSON.parse(value);
+}
+
+// Compatibility Method for the native JSON.stringify
+export function stringify(value: JSON): string {
+	return globalThis.JSON.stringify(value);
+}

package/tests/JSON.test.js

@@ -0,0 +1,131 @@
+const JSON = require('../build/JSON');
+
+describe('Testing JSON', () => {
+	test('Testing JSON.isNull', () => {
+		expect(JSON.isNull(null)).toBe(true);
+		expect(JSON.isNull(undefined)).toBe(false);
+		expect(JSON.isNull("Hello World")).toBe(false);
+	});
+
+	test('Testing JSON.isBoolean', () => {
+		expect(JSON.isBoolean(true)).toBe(true);
+		expect(JSON.isBoolean(false)).toBe(true);
+		expect(JSON.isBoolean("Hello World")).toBe(false);
+	});
+
+	test('Testing JSON.isNumber', () => {
+		expect(JSON.isNumber(42)).toBe(true);
+		expect(JSON.isNumber(Infinity)).toBe(false);
+		expect(JSON.isNumber(NaN)).toBe(false);
+	});
+
+	test('Testing JSON.isInteger', () => {
+		expect(JSON.isInteger(42)).toBe(true);
+		expect(JSON.isInteger(42.1)).toBe(false);
+		expect(JSON.isInteger(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
+	});
+
+	test('Testing JSON.isString', () => {
+		expect(JSON.isString("Hello World")).toBe(true);
+		expect(JSON.isString(42)).toBe(false);
+	});
+
+	test('Testing JSON.isShallowArray', () => {
+		expect(JSON.isShallowArray([null, 1, "Hello", { key: "World" }])).toBe(true);
+		expect(JSON.isShallowArray([null, 1, "Hello World", undefined])).toBe(true);
+		expect(JSON.isShallowArray({})).toBe(false);
+	});
+
+	test('Testing JSON.isArray', () => {
+		expect(JSON.isArray([null, 1, "Hello", { key: "World" }])).toBe(true);
+		expect(JSON.isArray([null, 1, "Hello World", undefined])).toBe(false);
+		expect(JSON.isArray({})).toBe(false);
+	});
+
+	test('Testing JSON.isShallowObject', () => {
+		expect(JSON.isShallowObject({ key: "Hello World", nested: { anotherKey: null } })).toBe(true);
+		expect(JSON.isShallowObject({ key: undefined })).toBe(true);
+		expect(JSON.isShallowObject([])).toBe(false);
+	});
+
+	test('Testing JSON.isObject', () => {
+		expect(JSON.isObject({ key: "Hello World", nested: { anotherKey: null } })).toBe(true);
+		expect(JSON.isObject({ key: undefined })).toBe(false);
+		expect(JSON.isShallowObject([])).toBe(false);
+	});
+
+	test('Testing JSON.isPrimitive', () => {
+		expect(JSON.isPrimitive(null)).toBe(false);
+		expect(JSON.isPrimitive(true)).toBe(true);
+		expect(JSON.isPrimitive(42)).toBe(true);
+		expect(JSON.isPrimitive("Hello World")).toBe(true);
+		expect(JSON.isPrimitive([])).toBe(false);
+		expect(JSON.isPrimitive({})).toBe(false);
+	});
+
+	test('Testing JSON.isShallowContainer', () => {
+		expect(JSON.isShallowContainer(null)).toBe(false);
+		expect(JSON.isShallowContainer(true)).toBe(false);
+		expect(JSON.isShallowContainer(42)).toBe(false);
+		expect(JSON.isShallowContainer("Hello World")).toBe(false);
+		expect(JSON.isShallowContainer([null, 1, "Hello", { key: "World" }])).toBe(true);
+		expect(JSON.isShallowContainer([null, 1, "Hello World", undefined])).toBe(true);
+		expect(JSON.isShallowContainer({ key: "Hello World", nested: { anotherKey: null } })).toBe(true);
+		expect(JSON.isShallowContainer({ key: undefined })).toBe(true);
+	});
+
+	test('Testing JSON.isContainer', () => {
+		expect(JSON.isContainer(null)).toBe(false);
+		expect(JSON.isContainer(true)).toBe(false);
+		expect(JSON.isContainer(42)).toBe(false);
+		expect(JSON.isContainer("Hello World")).toBe(false);
+		expect(JSON.isContainer([null, 1, "Hello", { key: "World" }])).toBe(true);
+		expect(JSON.isContainer([null, 1, "Hello World", undefined])).toBe(false);
+		expect(JSON.isContainer({ key: "Hello World", nested: { anotherKey: null } })).toBe(true);
+		expect(JSON.isContainer({ key: undefined })).toBe(false);
+	});
+
+	test('Testing JSON.isShallowJSON', () => {
+		expect(JSON.isShallowJSON(null)).toBe(true);
+		expect(JSON.isShallowJSON(true)).toBe(true);
+		expect(JSON.isShallowJSON(42)).toBe(true);
+		expect(JSON.isShallowJSON("Hello World")).toBe(true);
+		expect(JSON.isShallowJSON([null, 1, "Hello", { key: "World" }])).toBe(true);
+		expect(JSON.isShallowJSON([null, 1, "Hello World", undefined])).toBe(true);
+		expect(JSON.isShallowJSON({ key: "Hello World", nested: { anotherKey: null } })).toBe(true);
+		expect(JSON.isShallowJSON({ key: undefined })).toBe(true);
+	});
+
+	test('Testing JSON.isJSON', () => {
+		expect(JSON.isJSON(null)).toBe(true);
+		expect(JSON.isJSON(true)).toBe(true);
+		expect(JSON.isJSON(42)).toBe(true);
+		expect(JSON.isJSON("Hello World")).toBe(true);
+		expect(JSON.isJSON([null, 1, "Hello", { key: "World" }])).toBe(true);
+		expect(JSON.isJSON([null, 1, "Hello World", undefined])).toBe(false);
+		expect(JSON.isJSON({ key: "Hello World", nested: { anotherKey: null } })).toBe(true);
+		expect(JSON.isJSON({ key: undefined })).toBe(false);
+	});
+
+	test('Testing JSON.clone', () => {
+		const obj = { key: "Hello World", nested: [1, 2, { deep: true }] };
+		const clonedObj = JSON.clone(obj);
+
+		expect(clonedObj).toEqual(obj);
+		expect(clonedObj).not.toBe(obj);
+		expect(clonedObj.nested).not.toBe(obj.nested);
+		expect(clonedObj.nested[2]).not.toBe(obj.nested[2]);
+	});
+
+	test('Testing JSON.stringify', () => {
+		const data = { key: "Hello World", nested: [1, 2, { deep: true }] };
+
+		expect(JSON.stringify(data)).toBe('{"key":"Hello World","nested":[1,2,{"deep":true}]}');
+	});
+
+	test('Testing JSON.parse', () => {
+		const data = '{"key":"Hello World","nested":[1,2,{"deep":true}]}'
+
+		expect(JSON.parse(data)).toStrictEqual({ key: "Hello World", nested: [1, 2, { deep: true }] });
+	});
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		"target": "ES2024", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+		"module": "Node16", /* Specify what module code is generated. */
+		"rootDir": "./src", /* Specify the root folder within your source files. */
+		"outDir": "./build", /* Specify an output folder for all emitted files. */
+		"declaration": true, /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+		"declarationDir": "./types", /* Specify the output directory for generated declaration files. */
+		"forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
+		/* Type Checking */
+		"strict": true, /* Enable all strict type-checking options. */
+		"noImplicitAny": true, /* Enable error reporting for expressions and declarations with an implied 'any' type. */
+		"strictNullChecks": true, /* When type checking, take into account 'null' and 'undefined'. */
+		"strictFunctionTypes": true, /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+		"strictBindCallApply": true, /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
+		"strictPropertyInitialization": true, /* Check for class properties that are declared but not set in the constructor. */
+		"noImplicitThis": true, /* Enable error reporting when 'this' is given the type 'any'. */
+		"useUnknownInCatchVariables": true, /* Default catch clause variables as 'unknown' instead of 'any'. */
+		"alwaysStrict": true, /* Ensure 'use strict' is always emitted. */
+		"noUnusedLocals": true, /* Enable error reporting when local variables aren't read. */
+		"noUnusedParameters": true, /* Raise an error when a function parameter isn't read. */
+		"exactOptionalPropertyTypes": true, /* Interpret optional property types as written, rather than adding 'undefined'. */
+		"noImplicitReturns": true, /* Enable error reporting for codepaths that do not explicitly return in a function. */
+		"noFallthroughCasesInSwitch": true, /* Enable error reporting for fallthrough cases in switch statements. */
+		"noUncheckedIndexedAccess": true, /* Add 'undefined' to a type when accessed using an index. */
+		"noImplicitOverride": true, /* Ensure overriding members in derived classes are marked with an override modifier. */
+		"noPropertyAccessFromIndexSignature": true, /* Enforces using indexed accessors for keys declared using an indexed type. */
+	}
+}

package/types/JSON.d.ts

@@ -0,0 +1,37 @@
+export type Null = null;
+export type Boolean = boolean;
+export type Number = number;
+export type Integer = number;
+export type String = string;
+export type Array = JSON[];
+export type ShallowArray = unknown[];
+export type Object = {
+    [key: string]: JSON;
+};
+export type ShallowObject = {
+    [key: string]: unknown;
+};
+export type Primitive = Boolean | Number | String;
+export type Container = Array | Object;
+export type JSON = Null | Primitive | Container;
+export declare function isNull(value: unknown): value is Null;
+export declare function isBoolean(value: unknown): value is Boolean;
+export declare function isNumber(value: unknown): value is Number;
+export declare function isInteger(value: unknown): value is Integer;
+export declare function isString(value: unknown): value is String;
+export declare function isShallowArray(value: unknown): value is ShallowArray;
+export declare function isArray(value: unknown): value is Array;
+export declare function isShallowObject(value: unknown): value is ShallowObject;
+export declare function isObject(value: unknown): value is Object;
+export declare function isPrimitive(value: unknown): value is Primitive;
+export declare function isShallowContainer(value: unknown): value is unknown[] | {
+    [key: string]: unknown;
+};
+export declare function isContainer(value: unknown): value is Container;
+export declare function isShallowJSON(value: unknown): value is Null | Boolean | Number | String | unknown[] | {
+    [key: string]: unknown;
+};
+export declare function isJSON(value: unknown): value is JSON;
+export declare function clone<T extends JSON = JSON>(value: T): T;
+export declare function parse(value: string): JSON;
+export declare function stringify(value: JSON): string;