@serum-enterprises/json 2.0.1 → 3.1.0

package/README.md

@@ -1,6 +1,6 @@
 # JSON
 
-Type-Safe drop-in replacement for the native JSON Object
+Type-Safe drop-in replacement for the native JSON
 
 ## Installation
 
@@ -11,22 +11,23 @@ npm install --save @serum-enterprises/json
 ## Usage
 
 ```typescript
-import * as JSON from '@serum-enterprises/json';
+import {JSON} from '@serum-enterprises/json';
 
-const data: JSON.JSON = { name: 'John Doe', age: 25 };
+const data: JSON = { name: 'John Doe', age: 25 };
+const name: JSON.String = data.name;
 
-function verify(data: JSON.JSON): boolean {
+function verify(data: JSON): boolean {
 	if(!JSON.isObject(data))
 		return false;
 
-	if(!JSON.isString(data.name) || !JSON.isInteger(data.age))
+	if(!JSON.isString(data.name) || !JSON.isInteger(data.age))
 		return false;
 
 	return true;
 }
 
 if(verify(data)) {
-	console.log(`Data is correct: `);
+	console.log(`Data for ${name} is correct: `);
 	console.log(JSON.stringify(data, null, 2));
 }
 ```
@@ -35,6 +36,8 @@ if(verify(data)) {
 
 Please check [JSON.d.ts](./types/JSON.d.ts) for the full API.
 
+Please also note that functions prefixed with `_` are potentially mutating their Input.
+
 ## LICENSE
 
 MIT License

package/build/index.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON = void 0;
+var JSON;
+(function (JSON) {
+    function isNull(value) {
+        return value === null;
+    }
+    JSON.isNull = isNull;
+    function isBoolean(value) {
+        return typeof value === 'boolean';
+    }
+    JSON.isBoolean = isBoolean;
+    function isNumber(value) {
+        // Using Number.isFinite here as NaN, Infinity and -Infinity are not valid JSON Numbers
+        return Number.isFinite(value);
+    }
+    JSON.isNumber = isNumber;
+    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);
+    }
+    JSON.isInteger = isInteger;
+    function isString(value) {
+        return typeof value === 'string';
+    }
+    JSON.isString = isString;
+    function isShallowArray(value) {
+        return Array.isArray(value);
+    }
+    JSON.isShallowArray = isShallowArray;
+    function isArray(value) {
+        return isShallowArray(value) && value.every((v) => isJSON(v));
+    }
+    JSON.isArray = isArray;
+    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]');
+    }
+    JSON.isShallowObject = isShallowObject;
+    function isObject(value) {
+        return isShallowObject(value) && Object.values(value).every((v) => isJSON(v));
+    }
+    JSON.isObject = isObject;
+    function isPrimitive(value) {
+        return isBoolean(value) || isNumber(value) || isString(value);
+    }
+    JSON.isPrimitive = isPrimitive;
+    function isShallowContainer(value) {
+        return isShallowArray(value) || isShallowObject(value);
+    }
+    JSON.isShallowContainer = isShallowContainer;
+    function isContainer(value) {
+        return isArray(value) || isObject(value);
+    }
+    JSON.isContainer = isContainer;
+    function isShallowJSON(value) {
+        return isNull(value) || isPrimitive(value) || isShallowArray(value) || isShallowObject(value);
+    }
+    JSON.isShallowJSON = isShallowJSON;
+    function isJSON(value) {
+        return isNull(value) || isPrimitive(value) || isContainer(value);
+    }
+    JSON.isJSON = isJSON;
+    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;
+    }
+    JSON.clone = clone;
+    // Compatibility Method for the native JSON.parse
+    function parse(value) {
+        return globalThis.JSON.parse(value);
+    }
+    JSON.parse = parse;
+    // Compatibility Method for the native JSON.stringify
+    function stringify(value) {
+        return globalThis.JSON.stringify(value);
+    }
+    JSON.stringify = stringify;
+})(JSON || (exports.JSON = JSON = {}));

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "@serum-enterprises/json",
-	"version": "2.0.1",
+	"version": "3.1.0",
 	"engines": {
-		"node": ">=14.0.0"
+		"node": ">=24.0.0"
 	},
-	"description": "Type-Safe drop-in replacement for the native JSON Object",
-	"main": "./build/JSON.js",
-	"types": "./types/JSON.d.ts",
+	"description": "Type-Safe drop-in replacement for native JSON",
+	"main": "./build/index.js",
+	"types": "./types/index.d.ts",
 	"scripts": {
 		"build": "tsc",
 		"test": "jest"

package/types/index.d.ts

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

package/build/JSON.js

@@ -1,81 +0,0 @@
-"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/src/JSON.ts

@@ -1,91 +0,0 @@
-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

@@ -1,131 +0,0 @@
-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

@@ -1,29 +0,0 @@
-{
-	"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

@@ -1,37 +0,0 @@
-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;