Added isInt32(), assertIsInt32(), and jsonParse()

package.json

@@ -66,7 +66,7 @@
     "url": "https://github.com/webdeveric/utils/issues"
   },
   "homepage": "https://github.com/webdeveric/utils/#readme",
-  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0",
+  "packageManager": "pnpm@10.2.0+sha512.0d27364e0139c6aadeed65ada153135e0ca96c8da42123bd50047f961339dc7a758fc2e944b428f52be570d1bd3372455c1c65fa2e7aa0bfbf931190f9552001",
   "scripts": {
     "clean": "rimraf ./dist/",
     "prebuild": "pnpm clean",
@@ -85,13 +85,13 @@
   },
   "prettier": "@webdeveric/prettier-config",
   "devDependencies": {
-    "@commitlint/config-conventional": "^19.6.0",
+    "@commitlint/config-conventional": "^19.7.1",
     "@commitlint/types": "^19.5.0",
-    "@types/node": "^22.12.0",
-    "@vitest/coverage-v8": "^3.0.4",
+    "@types/node": "^22.13.1",
+    "@vitest/coverage-v8": "^3.0.5",
     "@webdeveric/eslint-config-ts": "^0.11.0",
     "@webdeveric/prettier-config": "^0.3.0",
-    "commitlint": "^19.6.1",
+    "commitlint": "^19.7.1",
     "commitlint-plugin-cspell": "^0.1.1",
     "conventional-changelog-conventionalcommits": "^8.0.0",
     "cspell": "^8.17.3",
@@ -107,6 +107,6 @@
     "semantic-release": "^24.2.1",
     "typescript": "^5.7.3",
     "validate-package-exports": "^0.8.0",
-    "vitest": "^3.0.4"
+    "vitest": "^3.0.5"
   }
 }

src/assertion/assertIsInt32.ts

@@ -0,0 +1,11 @@
+import { isInt32 } from '../predicate/isInt32.js';
+
+import { getError } from './getError.js';
+
+import type { Int32 } from '../types/numbers.js';
+
+export function assertIsInt32(input: unknown, error: string | Error = 'input is not an Int32'): asserts input is Int32 {
+  if (!isInt32(input)) {
+    throw getError(error);
+  }
+}

src/assertion/index.ts

@@ -7,6 +7,7 @@ export * from './assertIsBooleanArray.js';
 export * from './assertIsDigitsString.js';
 export * from './assertIsFiniteNumber.js';
 export * from './assertIsFunction.js';
+export * from './assertIsInt32.js';
 export * from './assertIsInteger.js';
 export * from './assertIsIntString.js';
 export * from './assertIsIterable.js';

src/index.ts

@@ -36,6 +36,7 @@ export * from './inRange.js';
 export * from './isEmpty.js';
 export * from './iterateForever.js';
 export * from './joinStrings.js';
+export * from './jsonParse.js';
 export * from './looksLikeURL.js';
 export * from './normalize.js';
 export * from './parseNumber.js';

src/jsonParse.ts

@@ -0,0 +1,17 @@
+import type { TypeAssertionFn } from './types/functions.js';
+
+export type JsonReviver = Parameters<JSON['parse']>[1];
+
+export function jsonParse(input: string): unknown;
+
+export function jsonParse(input: string, reviver?: JsonReviver): unknown;
+
+export function jsonParse<T>(input: string, reviver: JsonReviver | undefined, assertionFn: TypeAssertionFn<T>): T;
+
+export function jsonParse<T>(input: string, reviver?: JsonReviver, assertionFn?: TypeAssertionFn<T>): unknown {
+  const data: unknown = JSON.parse(input, reviver);
+
+  assertionFn?.(data);
+
+  return data;
+}

src/predicate/index.ts

@@ -9,6 +9,7 @@ export * from './isBooleanArray.js';
 export * from './isDigitsString.js';
 export * from './isFiniteNumber.js';
 export * from './isFunction.js';
+export * from './isInt32.js';
 export * from './isInteger.js';
 export * from './isIntString.js';
 export * from './isISODateString.js';

src/predicate/isInt32.ts

@@ -0,0 +1,8 @@
+import type { Int32 } from '../types/numbers.js';
+
+export function isInt32(input: unknown): input is Int32 {
+  const int32Min = -2_147_483_648;
+  const int32Max = 2_147_483_647;
+
+  return typeof input === 'number' && Number.isInteger(input) && input >= int32Min && input <= int32Max;
+}

src/types/branded.ts

@@ -1,7 +1,17 @@
+import type { Primitive } from './common.js';
+
 declare const brand: unique symbol;
 
-type Brand<Id> = {
+export type Brand<Id> = {
   [brand]: Id;
 };
 
 export type Branded<Type, Id> = Type & Brand<Id>;
+
+export type Unbranded<Type> = Type extends Branded<infer Inner, unknown> ? Omit<Inner, typeof brand> : Type;
+
+export type RemoveBranding<Type> = Type extends Primitive
+  ? Unbranded<Type>
+  : {
+      [Property in keyof Type]: Type extends Primitive ? Unbranded<Type[Property]> : RemoveBranding<Type[Property]>;
+    };

src/types/index.ts

@@ -3,6 +3,7 @@ export * from './branded.js';
 export * from './common.js';
 export * from './date-time.js';
 export * from './functions.js';
+export * from './numbers.js';
 export * from './objects.js';
 export * from './records.js';
 export * from './strings.js';

src/types/numbers.ts

@@ -0,0 +1,3 @@
+import type { Branded } from './branded.js';
+
+export type Int32 = Branded<number, 'Int32'>;

test/assertion/assertIsInt32.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+
+import { assertIsInt32 } from '../../src/assertion/assertIsInt32.js';
+
+describe('assertIsInt32()', () => {
+  it.each([null, undefined, 'not a number', Number.NaN, Infinity, Math.PI, Number.MAX_SAFE_INTEGER])(
+    'Throws when input is invalid: %s',
+    (input) => {
+      expect(() => {
+        assertIsInt32(input);
+      }).toThrowError();
+    },
+  );
+
+  it.each([-1, 0, 1, -2_147_483_648, 2_147_483_647])('Does not throw when input is valid: %s', (input) => {
+    expect(() => {
+      assertIsInt32(input);
+    }).not.toThrowError();
+  });
+});

test/jsonParse.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { assertIsObject } from '../src/assertion/assertIsObject.js';
+import { jsonParse } from '../src/jsonParse.js';
+
+describe('jsonParse()', () => {
+  it('Parses a JSON string', () => {
+    const unknownData = jsonParse('{"name":"test"}');
+
+    expect(unknownData).toEqual({
+      name: 'test',
+    });
+  });
+
+  it('Can use a reviver function', () => {
+    const unknownData = jsonParse('{"name":"test"}', (key, value) => {
+      return key === 'name' ? String(value).toUpperCase() : value;
+    });
+
+    expect(unknownData).toEqual({
+      name: 'TEST',
+    });
+  });
+
+  it('Can use a type assertion function', () => {
+    expect(jsonParse('{"name":"test"}', undefined, assertIsObject)).toEqual({
+      name: 'test',
+    });
+
+    expect(() => jsonParse('[]', undefined, assertIsObject)).toThrowError();
+  });
+});

test/predicate/isInt32.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+
+import { isInt32 } from '../../src/predicate/isInt32.js';
+
+describe('isInt32()', () => {
+  it('Returns true for valid input', () => {
+    expect(isInt32(1234)).toBeTruthy();
+  });
+
+  it('Returns false for invalid input', () => {
+    expect(isInt32(null)).toBeFalsy();
+    expect(isInt32(undefined)).toBeFalsy();
+    expect(isInt32(Number.MAX_SAFE_INTEGER)).toBeFalsy();
+  });
+
+  it('Can be used with Array.filter()', () => {
+    expect([-1, 0, null, 2, undefined, 4, Number.MAX_SAFE_INTEGER, Number.POSITIVE_INFINITY].filter(isInt32)).toEqual([
+      -1, 0, 2, 4,
+    ]);
+  });
+});