@assemblerjs/core

Internal utilities package for the AssemblerJS ecosystem.

Overview

@assemblerjs/core provides shared utilities used across all AssemblerJS packages. When building applications with assemblerjs, you'll commonly need to import utilities from this package, such as Task and other helper types.

This package is automatically installed as a dependency of assemblerjs, but it's designed to be imported directly in your code alongside the main library.

What's Inside

This package contains commonly used utilities:

• Task - Async task utilities for concurrent operations
• Type utilities and helpers - Generic TypeScript types and type guards
• Collection management - Utilities for working with arrays, maps, and sets
• Error handling - Custom error classes and error utilities
• Conditional utilities - Helper functions for conditional logic
• Array manipulation - Enhanced array operations

Installation

This package is automatically installed as a dependency when you install assemblerjs:

npm install assemblerjs
# @assemblerjs/core is installed automatically

You can also install it independently if you only need the core utilities:

npm install @assemblerjs/core
# or
yarn add @assemblerjs/core

Usage

When building applications with AssemblerJS, you'll commonly import utilities from this package:

import { Task } from '@assemblerjs/core';
import { Assemblage, Assembler, AbstractAssemblage } from 'assemblerjs';

@Assemblage()
class MyService implements AbstractAssemblage {
  async processItems(items: string[]) {
    // Use Task for concurrent operations
    const results = await Task.all(
      items.map(item => this.processItem(item))
    );
    return results;
  }

  private async processItem(item: string) {
    // Process individual item
    return item.toUpperCase();
  }
}

Common Exports

// Task utilities for async operations
import { Task } from '@assemblerjs/core';

// Type utilities
import { /* type helpers */ } from '@assemblerjs/core';

// Collection utilities
import { /* collection helpers */ } from '@assemblerjs/core';

Method Decorators

@assemblerjs/core also exports method decorators, including Await.

import { Await } from '@assemblerjs/core';

Await delays method execution until a condition becomes truthy.

Await(
  condition: string | ((instance?: any) => boolean | Promise<boolean>),
  interval?: number
)

• condition can be:
  • the name of a boolean property (example: 'ready')
  • the name of a sync/async method returning a boolean (example: 'isReady')
  • a standalone sync/async function that may ignore the instance parameter
• interval is the polling interval in milliseconds (default: 25)

Examples:

class Service {
  ready = false;

  @Await('ready')
  async start() {
    return 'started';
  }
}

class AnotherService {
  private connected = false;

  isConnected() {
    return this.connected;
  }

  @Await('isConnected', 10)
  async fetch() {
    return 'ok';
  }
}

let featureEnabled = false;

class ExternalConditionService {
  @Await(async () => featureEnabled)
  async run() {
    return true;
  }
}

For Contributors

Development

# Build the package
npx nx build core

# Run tests
npx nx test core

# Lint
npx nx lint core

Package Dependencies

This package is a dependency of:

• assemblerjs - Core DI library
• @assemblerjs/electron - Electron integration
• @assemblerjs/mongo - MongoDB integration
• @assemblerjs/rest - REST framework

Architecture

As an internal package, @assemblerjs/core follows these principles:

• Zero external dependencies - Keeps the dependency tree minimal
• Pure utilities - No side effects or global state
• Tree-shakable - Optimized for bundle size
• Type-safe - Full TypeScript support

License

MIT

Part of the AssemblerJS monorepo