SpectraGraph Utils

Common utility functions used across the SpectraGraph ecosystem. This package provides lightweight helper functions for functional programming patterns, data transformation, and common operations that are shared between SpectraGraph packages.

Overview

SpectraGraph Utils is built around several key principles:

• Functional: Pure functions with predictable behavior and no side effects
• Type-safe: Comprehensive TypeScript support with generic type definitions
• Null-safe: Graceful handling of null and undefined values
• Minimal: Small, focused utilities without external dependencies

Installation

npm install @spectragraph/utils

Core Concepts

Utility Functions

The package provides utility functions that handle common patterns in data processing:

• Property Access: Safe, flexible path-based property access with wildcard support
• Mapping: Apply functions to single items or arrays uniformly
• Piping: Chain operations together in a functional style
• Null handling: Safe operations that gracefully handle null/undefined values

API Reference

get(objOrArray, path, allowWildcards)

Gets a value from an object using a property path. Supports the $ wildcard for array element iteration and flattening. Supports both dot notation and bracket notation.

Parameters:

• objOrArray (Object | Array) - The object or array to query
• path (string | Array) - The path of the property to get. Use "$" to iterate over array elements.
• allowWildcards (boolean, optional) - Whether to allow wildcard ($) in paths. Default: false

Returns: The resolved value, null if the input is null/undefined, or undefined if the property is not found

Examples:

import { get } from "@spectragraph/utils";

// Simple property access
const bear = {
  name: "Tenderheart Bear",
  yearIntroduced: 1982,
  home: { name: "Care-a-Lot" }
};

get(bear, "name");              // "Tenderheart Bear"
get(bear, "home.name");         // "Care-a-Lot"
get(bear, "bestFriend");        // undefined

// Bracket notation
const bears = [
  { name: "Tenderheart Bear" },
  { name: "Cheer Bear" }
];

get(bears, "[0].name");         // "Tenderheart Bear"
get(bears, "[1].name");         // "Cheer Bear"

// Wildcard ($) for array iteration
const bear = {
  name: "Wish Bear",
  powers: [
    { name: "Care Bear Stare" },
    { name: "Make a Wish" }
  ]
};

get(bear, "powers.$.name", true);  // ["Care Bear Stare", "Make a Wish"]

// Nested wildcards
const home = {
  name: "Care-a-Lot",
  residents: [
    {
      name: "Tenderheart Bear",
      powers: [{ name: "Care Bear Stare" }]
    },
    {
      name: "Cheer Bear",
      powers: [{ name: "Care Bear Stare" }]
    }
  ]
};

get(home, "residents.$.name", true);           // ["Tenderheart Bear", "Cheer Bear"]
get(home, "residents.$.powers.$.name", true);  // ["Care Bear Stare", "Care Bear Stare"]

applyOrMap(itemItemsOrNull, fn)

Applies a function to an item or maps it over an array of items. Handles null and undefined gracefully by returning them unchanged.

Parameters:

• itemItemsOrNull (T | T[] | null | undefined) - Single item, array of items, or null/undefined
• fn (Function) - Function to apply to each item

Returns: Result of applying fn to the item(s), or null/undefined if input was null/undefined

import { applyOrMap } from "@spectragraph/utils";

// Single item
applyOrMap(5, (x) => x * 2); // Returns: 10

// Array of items
applyOrMap([1, 2, 3], (x) => x * 2); // Returns: [2, 4, 6]

// Null/undefined handling
applyOrMap(null, (x) => x * 2); // Returns: null
applyOrMap(undefined, (x) => x * 2); // Returns: undefined

applyOrMapAsync(itemItemsOrNull, asyncFn)

Applies an async function to an item or maps it over an array of items. Handles null and undefined gracefully.

Parameters:

• itemItemsOrNull (T | T[] | null | undefined) - Single item, array of items, or null/undefined
• asyncFn (Function) - Async function to apply to each item

Returns: Promise resolving to the result of applying asyncFn to the item(s), or null/undefined if input was null/undefined

import { applyOrMapAsync } from "@spectragraph/utils";

// Single item
await applyOrMapAsync(5, async (x) => x * 2); // Returns: 10

// Array of items
await applyOrMapAsync([1, 2, 3], async (x) => x * 2); // Returns: [2, 4, 6]

// Null/undefined handling
applyOrMapAsync(null, async (x) => x * 2); // Returns: null
applyOrMapAsync(undefined, async (x) => x * 2); // Returns: undefined

pipeThru(init, fns)

Pipes a value through a series of functions in sequence. Each function receives the result of the previous function.

Parameters:

• init (T) - Initial value to pipe through the functions
• fns (Function[]) - Array of functions to pipe the value through

Returns: The result after applying all functions in sequence

import { pipeThru } from "@spectragraph/utils";

const add5 = (x) => x + 5;
const multiply2 = (x) => x * 2;
const toString = (x) => x.toString();

pipeThru(10, [add5, multiply2, toString]); // Returns: "30"

Examples

Property Access and Path Navigation

import { get } from "@spectragraph/utils";

// Working with deeply nested data
const careBear = {
  name: "Tenderheart Bear",
  home: {
    name: "Care-a-Lot",
    location: {
      realm: "Cloud Kingdom",
      coordinates: { x: 100, y: 200 }
    }
  },
  powers: [
    { name: "Care Bear Stare", type: "group" },
    { name: "Healing Touch", type: "individual" }
  ]
};

// Simple nested access
get(careBear, "home.location.realm");  // "Cloud Kingdom"
get(careBear, "home.location.coordinates.x");  // 100

// Extract all power names using wildcard
get(careBear, "powers.$.name", true);  // ["Care Bear Stare", "Healing Touch"]

// Filter and extract with additional processing
const powerTypes = get(careBear, "powers.$.type", true);
// ["group", "individual"]

Working with SpectraGraph Resources

import { get } from "@spectragraph/utils";

// Typical SpectraGraph resource structure
const resource = {
  type: "bears",
  id: "1",
  attributes: {
    name: "Tenderheart Bear",
    yearIntroduced: 1982
  },
  relationships: {
    home: { type: "homes", id: 1 },
    powers: [
      { type: "powers", id: "careBearStare" },
      { type: "powers", id: "healing" }
    ]
  }
};

// Access attributes
get(resource, "attributes.name");  // "Tenderheart Bear"

// Access relationship IDs
get(resource, "relationships.home.id");  // 1
get(resource, "relationships.powers.$.id", true);  // ["careBearStare", "healing"]

Data Transformation

import { applyOrMap, pipeThru } from "@spectragraph/utils";

// Transform data that might be a single item or array
const data = [{ name: "John" }, { name: "Jane" }];

const addGreeting = (person) => ({
  ...person,
  greeting: `Hello, ${person.name}`,
});
const toUpperCase = (person) => ({
  ...person,
  name: person.name.toUpperCase(),
});

const result = applyOrMap(data, (person) =>
  pipeThru(person, [addGreeting, toUpperCase]),
);

console.log(result);
// [
//   { name: "JOHN", greeting: "Hello, John" },
//   { name: "JANE", greeting: "Hello, Jane" }
// ]

Async Data Processing

import { applyOrMapAsync } from "@spectragraph/utils";

async function fetchUserDetails(userId) {
  const response = await fetch(`/api/users/${userId}`);
  return response.json();
}

// Works with both single IDs and arrays of IDs
const userIds = ["user-1", "user-2", "user-3"];
const userDetails = await applyOrMapAsync(userIds, fetchUserDetails);

// Also works with a single ID
const singleUser = await applyOrMapAsync("user-1", fetchUserDetails);

Pipeline Processing

import { pipeThru } from "@spectragraph/utils";

// Define transformation steps
const parseJson = (str) => JSON.parse(str);
const extractUsers = (data) => data.users;
const filterActive = (users) => users.filter((u) => u.active);
const sortByName = (users) =>
  users.sort((a, b) => a.name.localeCompare(b.name));

// Process data through the pipeline
const rawData =
  '{"users": [{"name": "Bob", "active": true}, {"name": "Serafina", "active": false}]}';

const result = pipeThru(rawData, [
  parseJson,
  extractUsers,
  filterActive,
  sortByName,
]);

console.log(result); // [{ name: "Bob", active: true }]

Null-Safe Operations

import { applyOrMap } from "@spectragraph/utils";

// Safely handle potentially null/undefined data
function processUserData(userData) {
  return applyOrMap(userData, (user) => ({
    ...user,
    displayName: user.firstName + " " + user.lastName,
  }));
}

processUserData(null); // Returns: null
processUserData(undefined); // Returns: undefined
processUserData(user); // Returns: processed user
processUserData([user1, user2]); // Returns: [processed user1, processed user2]

Resource Processing in SpectraGraph

import { applyOrMap, pipeThru } from "@spectragraph/utils";

// Common pattern in SpectraGraph packages
function normalizeResources(resources) {
  const addType = (resource) => ({
    ...resource,
    type: resource.type || "unknown",
  });
  const addId = (resource) => ({
    ...resource,
    id: resource.id || generateId(),
  });
  const validateRequired = (resource) => {
    if (!resource.attributes) throw new Error("Missing attributes");
    return resource;
  };

  return applyOrMap(resources, (resource) =>
    pipeThru(resource, [addType, addId, validateRequired]),
  );
}

// Works with single resources or arrays
const singleResource = { attributes: { name: "Test" } };
const multipleResources = [
  { attributes: { name: "Test 1" } },
  { attributes: { name: "Test 2" } },
];

const normalizedSingle = normalizeResources(singleResource);
const normalizedMultiple = normalizeResources(multipleResources);

TypeScript Support

SpectraGraph Utils includes comprehensive TypeScript definitions:

import { get, applyOrMap, applyOrMapAsync, pipeThru } from "@spectragraph/utils";

// Property access
interface Bear {
  name: string;
  home: { name: string; location: string };
  powers: Array<{ name: string; type: string }>;
}

const bear: Bear = {
  name: "Tenderheart Bear",
  home: { name: "Care-a-Lot", location: "Cloud Kingdom" },
  powers: [{ name: "Care Bear Stare", type: "group" }]
};

const homeName: any = get(bear, "home.name");  // Type: any
const powerNames: any = get(bear, "powers.$.name", true);  // Type: any

// Type-safe transformations
const numbers: number[] = [1, 2, 3];
const doubled: number[] = applyOrMap(numbers, (x) => x * 2);

// Async operations
const asyncResult: Promise<string[]> = applyOrMapAsync(
  ["a", "b", "c"],
  async (str: string): Promise<string> => str.toUpperCase(),
);

// Pipeline with type inference
const result: string = pipeThru(42, [
  (x: number) => x * 2, // number -> number
  (x: number) => x.toString(), // number -> string
  (x: string) => x.padStart(4, "0"), // string -> string
]);

Performance Considerations

Functional Programming Benefits

• Immutability: Functions don't modify input data, reducing bugs
• Composability: Small functions can be combined in different ways
• Testability: Pure functions are easy to test in isolation
• Predictability: Same inputs always produce same outputs

Memory Efficiency

• No dependencies: Minimal memory footprint
• Small functions: Only include what you need
• Lazy evaluation: Operations are only performed when needed

Usage Patterns

// Efficient: Process in pipelines
const result = pipeThru(data, [transform1, transform2, transform3]);

// Less efficient: Multiple intermediate variables
const step1 = transform1(data);
const step2 = transform2(step1);
const step3 = transform3(step2);

Related Packages

• @spectragraph/core - Uses utils for resource and query processing
• @spectragraph/memory-store - Uses utils for data transformations
• @spectragraph/postgres-store - Uses utils for SQL query building