tessl/npm-lumino--coreutils

Essential utility functions and classes for TypeScript/JavaScript applications including JSON handling, MIME data management, promise delegation, secure tokens, and cross-platform random number generation.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

JSON Utilities

Name: tessl/npm-lumino--coreutils
Author: tessl

Comprehensive type system and utilities for type-safe JSON data manipulation including deep equality comparison, deep copying, and type checking functions with support for readonly and partial variants.

Capabilities

JSON Type System

Complete TypeScript type definitions for JSON data with support for readonly and partial variants.

// Primitive JSON Types
type JSONPrimitive = boolean | number | string | null;

// Core JSON Types
type JSONValue = JSONPrimitive | JSONObject | JSONArray;
interface JSONObject {
  [key: string]: JSONValue;
}
interface JSONArray extends Array<JSONValue> {}

// Readonly JSON Types
type ReadonlyJSONValue = JSONPrimitive | ReadonlyJSONObject | ReadonlyJSONArray;
interface ReadonlyJSONObject {
  readonly [key: string]: ReadonlyJSONValue;
}
interface ReadonlyJSONArray extends ReadonlyArray<ReadonlyJSONValue> {}

// Partial JSON Types (allows undefined values)
type PartialJSONValue = JSONPrimitive | PartialJSONObject | PartialJSONArray;
interface PartialJSONObject {
  [key: string]: PartialJSONValue | undefined;
}
interface PartialJSONArray extends Array<PartialJSONValue> {}

// Readonly Partial JSON Types
type ReadonlyPartialJSONValue = JSONPrimitive | ReadonlyPartialJSONObject | ReadonlyPartialJSONArray;
interface ReadonlyPartialJSONObject {
  readonly [key: string]: ReadonlyPartialJSONValue | undefined;
}
interface ReadonlyPartialJSONArray extends ReadonlyArray<ReadonlyPartialJSONValue> {}

JSONExt Namespace

Utility functions and constants for JSON data manipulation.

namespace JSONExt {
  /**
   * Shared frozen empty JSON object constant
   */
  const emptyObject: ReadonlyJSONObject;
  
  /**
   * Shared frozen empty JSON array constant
   */
  const emptyArray: ReadonlyJSONArray;
  
  /**
   * Test whether a JSON value is a primitive
   * @param value - The JSON value to test
   * @returns true if the value is a primitive (boolean, number, string, or null)
   */
  function isPrimitive(value: ReadonlyPartialJSONValue): value is JSONPrimitive;
  
  /**
   * Test whether a JSON value is an array (overloaded for different JSON types)
   * @param value - The JSON value to test
   * @returns true if the value is an array
   */
  function isArray(value: JSONValue): value is JSONArray;
  function isArray(value: ReadonlyJSONValue): value is ReadonlyJSONArray;
  function isArray(value: PartialJSONValue): value is PartialJSONArray;
  function isArray(value: ReadonlyPartialJSONValue): value is ReadonlyPartialJSONArray;
  
  /**
   * Test whether a JSON value is an object (overloaded for different JSON types)
   * @param value - The JSON value to test
   * @returns true if the value is an object (not primitive or array)
   */
  function isObject(value: JSONValue): value is JSONObject;
  function isObject(value: ReadonlyJSONValue): value is ReadonlyJSONObject;
  function isObject(value: PartialJSONValue): value is PartialJSONObject;
  function isObject(value: ReadonlyPartialJSONValue): value is ReadonlyPartialJSONObject;
  
  /**
   * Compare two JSON values for deep equality
   * @param first - The first JSON value to compare
   * @param second - The second JSON value to compare
   * @returns true if the values are deeply equal, false otherwise
   */
  function deepEqual(
    first: ReadonlyPartialJSONValue,
    second: ReadonlyPartialJSONValue
  ): boolean;
  
  /**
   * Create a deep copy of a JSON value
   * @param value - The JSON value to copy
   * @returns A deep copy of the given JSON value
   */
  function deepCopy<T extends ReadonlyPartialJSONValue>(value: T): T;
}

Usage Examples:

import { JSONExt, JSONValue, JSONObject } from "@lumino/coreutils";

// Using constants
const defaultConfig = JSONExt.emptyObject;
const defaultItems = JSONExt.emptyArray;

// Type checking
const data: JSONValue = { name: "Alice", scores: [95, 87, 92] };

if (JSONExt.isPrimitive(data)) {
  // data is boolean | number | string | null
  console.log("Primitive value:", data);
} else if (JSONExt.isArray(data)) {
  // data is JSONArray
  console.log("Array length:", data.length);
} else if (JSONExt.isObject(data)) {
  // data is JSONObject
  console.log("Object keys:", Object.keys(data));
}

// Deep equality comparison
const obj1 = { a: 1, b: { c: 2, d: [3, 4] } };
const obj2 = { a: 1, b: { c: 2, d: [3, 4] } };
const isEqual = JSONExt.deepEqual(obj1, obj2); // true

// Deep copying
const original = { user: { name: "Bob", preferences: { theme: "dark" } } };
const copy = JSONExt.deepCopy(original);
copy.user.name = "Charlie"; // original.user.name remains "Bob"

// Working with partial data (allows undefined)
const partialUser = { name: "Alice", age: undefined, email: "alice@example.com" };
const userCopy = JSONExt.deepCopy(partialUser);

Constants

Pre-defined immutable JSON objects for common use cases.

/**
 * Shared frozen empty JSON object - use instead of creating new empty objects
 */
const emptyObject: ReadonlyJSONObject;

/**
 * Shared frozen empty JSON array - use instead of creating new empty arrays
 */
const emptyArray: ReadonlyJSONArray;

Usage Examples:

import { JSONExt } from "@lumino/coreutils";

// Use shared constants instead of creating new objects
const defaultSettings = JSONExt.emptyObject;
const defaultItems = JSONExt.emptyArray;

// These are frozen objects, cannot be modified
try {
  defaultSettings.newProperty = "value"; // TypeError in strict mode
} catch (error) {
  console.log("Cannot modify frozen object");
}