Package Exports

@protorians/core
@protorians/core/appearance
@protorians/core/appearance.js
@protorians/core/event-dispatcher
@protorians/core/event-dispatcher.js
@protorians/core/index.ts
@protorians/core/navigation
@protorians/core/navigation.js
@protorians/core/presenters
@protorians/core/presenters.js
@protorians/core/utilities
@protorians/core/utilities.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@protorians/core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@protorians/core

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

Overview
Installation
Core Concepts
Basic Usage
Advanced Features
API Reference
- Signals
  - Properties
  - Methods
- Dictionary
  - Properties
  - Methods
- Climbing
  - Properties
  - Methods
- Utilities
  - Text
  - Number
  - Object
  - Date
  - URL
  - HTML
Types Reference
License

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.

@protorians/core

Package Exports

Readme

@protorians/core

Table of Contents

Overview

Installation

Core Concepts

Signals

Dictionaries

Collections

Environment

Climbing

Basic Usage

Advanced Features

Signal Stack

Signal Controller

Dictionary

Utilities

API Reference

Signals

Properties

Methods

Dictionary

Properties

Methods

Utilities

Text

Number

Object

Types Reference

License