JSPM

@protorians/core

0.1.11
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 95
  • Score
    100M100P100Q107975F
  • License MIT

Protorians Core

Package Exports

    Readme

    @protorians/core

    A powerful, flexible utility library for modern JavaScript and TypeScript applications.

    Table of Contents

    Overview

    @protorians/core is a comprehensive utility library that provides a foundation for building modern JavaScript and TypeScript applications. It includes utilities for event handling, state management, data structures, and common operations on strings, numbers, objects, and more.

    Installation

    # Using npm
npm install @protorians/core

# Using yarn
yarn add @protorians/core

# Using pnpm
pnpm add @protorians/core

    Core Concepts

    Signals

    Signals are a powerful event handling system that allows you to create, dispatch, and listen for events in your application. Protorians Core provides two main interfaces for signals:

    • SignalStack: A stack-based event system for registering listeners and dispatching events.
    • SignalController: A reactive state management system that allows you to track and respond to state changes.
    import { Signal } from '@protorians/core';

// Create a signal stack
const signal = new Signal.Stack<{
  click: { x: number; y: number };
  hover: { element: HTMLElement };
}>();

// Listen for events
signal.listen('click', ({ x, y }) => {
  console.log(`Clicked at (${x}, ${y})`);
});

// Dispatch events
signal.dispatch('click', { x: 100, y: 200 });

    Dictionaries

    Dictionaries are key-value stores with a rich API for manipulating and accessing data. They provide type-safe access to values and methods for transforming the data.

    import { Dictionary } from '@protorians/core';

// Create a dictionary
const dict = new Dictionary<{
  name: string;
  age: number;
  email: string;
}>();

// Set values
dict.set('name', 'John Doe');
dict.set('age', 30);
dict.set('email', 'john@example.com');

// Get values
console.log(dict.get('name')); // 'John Doe'

// Convert to array
console.log(dict.array); // [['name', 'John Doe'], ['age', 30], ['email', 'john@example.com']]

    Collections

    Collections are ordered lists of items with methods for adding, removing, and manipulating items. They provide a more powerful alternative to arrays.

    import { Collection } from '@protorians/core';

// Create a collection
const collection = new Collection<string>();

// Add items
collection.add('apple');
collection.add('banana');
collection.add('orange');

// Check if an item exists
console.log(collection.has('banana')); // true

// Remove an item
collection.remove('banana');

// Iterate over items
collection.each((item, index) => {
  console.log(`Item ${index}: ${item}`);
});

    Environment

    The Environment utility provides information about the current execution environment, such as whether the code is running in a browser, Node.js, or a service worker.

    import { Environment } from '@protorians/core';

if (Environment.Client) {
  // Code running in a browser
  console.log('Running in a browser');
} else if (Environment.Server) {
  // Code running in Node.js
  console.log('Running in Node.js');
}

    Climbing

    The Climbing utility provides a way to process arrays of items asynchronously in sequence. It's particularly useful for handling operations that need to be performed one after another, with each step potentially being asynchronous.

    import { Climbing } from '@protorians/core';

// Array of items to process
const items = [1, 2, 3, 4, 5];

// Create a new Climbing instance
const climbing = new Climbing(
  items,
  // Async callback function that processes each item
  async (index) => {
    const item = items[index];
    console.log(`Processing item ${item}`);

    // Simulate async operation
    await new Promise(resolve => setTimeout(resolve, 1000));

    return item * 2; // Return processed result
  }
);

// Trigger the climbing process
climbing.trigger((result) => {
  console.log('All items processed');
  console.log('Results:', result.responses); // [2, 4, 6, 8, 10]
});

    The Climbing class provides the following features:

    • Sequential processing of array items
    • Asynchronous operation support
    • Collection of processed results
    • Error handling with strict and non-strict modes
    • Control over the starting point of processing

    Basic Usage

    import {
    Signal,
    Dictionary,
    Collection,
    Environment,
    NumberUtility,
    TextUtility,
    ObjectUtility,
} from '@protorians/core';


// Create a signal stack
const signal = new Signal.Stack<{
    update: { value: number };
}>();

// Listen for events
signal.listen('update', ({value}) => {
    console.log(`Value updated to ${value}`);
});

// Create a dictionary
const dict = new Dictionary<{
    count: number;
}>();

// Set initial value
dict.set('count', 0);

// Update the value and dispatch an event
function increment() {
    const currentCount = dict.get('count');
    dict.set('count', currentCount + 1);
    signal.dispatch('update', {value: currentCount + 1});
}

// Use text utilities
const slug = TextUtility.slugify('Hello World!'); // 'hello-world'
const truncated = TextUtility.truncate('This is a long text', 10); // 'This is a...'

// Use number utilities
const formatted = NumberUtility.isNumber(1234.56); // true

// Use array utilities
const merged = ObjectUtility.unWrap([[1, 2, 3, [4, 5, 6]], [7, 8], [9]]); // [1, 2, 3, 4, 5, 6, 7, 8, 9]

    Advanced Features

    Signal Stack

    The Signal Stack provides a powerful event system with features like:

    • Event Prioritization: Control the order in which listeners are called.
    • Cancellable Events: Allow listeners to cancel the event propagation.
    • Computed Values: Get the computed result of an event dispatch.
    import { Signal } from '@protorians/core';

const signal = new Signal.Stack<{
  calculate: { a: number; b: number };
}>();

// Add a listener with high priority
signal.listen('calculate', ({ a, b }) => {
  return a + b;
});

// Add a listener with lower priority
signal.listen('calculate', ({ a, b }) => {
  console.log(`Calculating ${a} + ${b}`);
});

// Dispatch and get the computed result
signal.dispatch('calculate', { a: 5, b: 3 });
const result = signal.computed<number>('calculate');
console.log(result); // 8

    Signal Controller

    The Signal Controller provides reactive state management with features like:

    • State Tracking: Track changes to state properties.
    • Effect Callbacks: Execute callbacks when state changes.
    • State Reset: Reset state to its original values.
    import { Signal } from '@protorians/core';

// Create a state object
const state = {
  count: 0,
  name: 'John'
};

// Create a signal controller
const controller = new Signal.Controller(state);

// Add an effect callback
controller.effect(({ target, name, value }) => {
  console.log(`Property ${String(name)} changed to ${value}`);
});

// Update state
controller.assign('count', 1); // Logs: Property count changed to 1
controller.assign('name', 'Jane'); // Logs: Property name changed to Jane

// Reset state
controller.reset(state);

    Dictionary

    The Dictionary class provides advanced features for working with key-value data:

    • Type Safety: Ensure type safety for keys and values.
    • Data Transformation: Transform data using parsers.
    • Serialization: Convert to and from strings.
    import { Dictionary } from '@protorians/core';

// Create a dictionary with initial values
const dict = new Dictionary<{
  name: string;
  age: number;
  email: string;
}>({
  name: 'John Doe',
  age: 30,
  email: 'john@example.com'
});

// Transform values
dict.parse((key, value) => {
  if (key === 'name') {
    return value.toUpperCase();
  }
  return value;
});

console.log(dict.get('name')); // 'JOHN DOE'

// Convert to string
const str = dict.string;
console.log(str); // '{"name":"JOHN DOE","age":30,"email":"john@example.com"}'

// Create from string
const newDict = new Dictionary<{
  foo: string;
  bar: number;
}>();
newDict.fromString('{"foo":"hello","bar":42}');
console.log(newDict.get('foo')); // 'hello'

    Utilities

    Protorians Core provides a rich set of utilities for common operations:

    import {
    HTMLUtility,
    NumberUtility,
    TextUtility,
    ObjectUtility,
} from '@protorians/core';

// Text utilities
const camelCase = TextUtility.camelCase('hello-world'); // 'helloWorld'
const kebabCase = TextUtility.kebabCase('helloWorld'); // 'hello-world'
const capitalize = TextUtility.capitalize('hello'); // 'Hello'

// Number utilities
const clamp = NumberUtility.clamp(150, 0, 100); // 100
const pad = NumberUtility.pad(5, 3); // '005'
const isEven = NumberUtility.isEven(4); // true

// Object utilities
const clone = ObjectUtility.clone({a: 1, b: {c: 2}}); // Object clone
const omit = ObjectUtility.omit({a: 1, b: 2, c: 3}, ['b']); // { a: 1, c: 3 }

// HTML utilities
const escape = HTMLUtility.escape('<div>Hello</div>'); // '&lt;div&gt;Hello&lt;/div&gt;'
const unescape = HTMLUtility.unescape('&lt;div&gt;Hello&lt;/div&gt;'); // '<div>Hello</div>'
const stripTags = HTMLUtility.stripTags('<p>Hello <b>World</b></p>'); // 'Hello World'

    API Reference

    Signals

    The Signals module provides tools for event handling and state management.

    Properties

    • Stack: Class for creating event stacks
    • Controller: Class for creating reactive state controllers

    Methods

    Signal.Stack:

    • listen(type, callable, options): Adds a listener for an event
    • dispatch(type, payload): Dispatches an event
    • computed<T>(type): Gets the computed result of an event
    • remove(type, index): Removes a listener by index
    • removeStack(type): Removes all listeners for an event
    • removeCallable(callable, type): Removes a specific listener
    • clear(): Removes all listeners

    Signal.Controller:

    • update(target): Updates the state
    • reset(target): Resets the state
    • assign(key, value): Assigns a value to a state property
    • effect(callable): Adds an effect callback
    • trigger(name, value): Triggers an effect
    • compute(): Computes the current state

    Dictionary

    The Dictionary class provides a type-safe key-value store.

    Properties

    • map: Gets the underlying object
    • array: Gets the dictionary as an array of key-value pairs
    • string: Gets the dictionary as a JSON string

    Methods

    • get(key): Gets a value by key
    • set(key, value): Sets a value by key
    • remove(key): Removes a key
    • clear(): Removes all keys
    • fromString(data): Initializes from a JSON string
    • parse(callable): Transforms values using a parser
    • many(values): Sets multiple values
    • values(): Gets all values
    • keys(): Gets all keys

    Utilities

    Protorians Core provides various utility modules for common operations.

    Text

    • camelCase(str): Converts a string to camelCase
    • kebabCase(str): Converts a string to kebab-case
    • snakeCase(str): Converts a string to snake_case
    • capitalize(str): Capitalizes the first letter
    • truncate(str, length, suffix): Truncates a string
    • slugify(str): Converts a string to a URL-friendly slug
    • trimSpace(str): Trims and normalizes whitespace
    • pad(str, length, char): Pads a string to a specific length

    Number

    • format(num, decimals, decimalSeparator, thousandsSeparator): Formats a number
    • random(min, max): Generates a random number
    • clamp(num, min, max): Clamps a number between min and max
    • pad(num, length): Pads a number with leading zeros
    • isEven(num): Checks if a number is even
    • isOdd(num): Checks if a number is odd
    • round(num, decimals): Rounds a number to a specific number of decimals

    Object

    • clone(obj): Deep clones an object
    • merge(obj1, obj2): Merges two objects
    • pick(obj, keys): Creates a new object with selected keys
    • omit(obj, keys): Creates a new object without specified keys
    • isEqual(obj1, obj2): Checks if two objects are equal
    • isEmpty(obj): Checks if an object is empty
    • entries(obj): Gets an array of key-value pairs
    • fromEntries(entries): Creates an object from key-value pairs

    Types Reference

    Category Type Description
    Signal Types ISignalStack<M> Interface for signal stacks with generic event map
    ISignalController<I> Interface for reactive state controllers
    ISignalStackCallable<P> Type for signal stack callback functions
    ISignalStackOptions Options for signal stack listeners
    Dictionary Types IDictionary<T> Interface for dictionaries with generic value types
    IDictionaryCallbackParser<T> Type for dictionary value parsers
    Collection Types ICollection<T> Interface for collections with generic item types
    ICollectionCallable<T> Type for collection callback functions
    Environment Types IEnvironment Interface for environment detection
    Utility Types ITextUtilities Interface for text utilities
    INumberUtilities Interface for number utilities
    IObjectUtilities Interface for object utilities
    IDateUtilities Interface for date utilities
    IURLUtilities Interface for URL utilities
    IHTMLUtilities Interface for HTML utilities

    License

    This project is licensed under the MIT License. See the LICENSE file for details.