@cc-ts/helpers NPM

@cc-ts/helpers 🛠️

A collection of powerful utilities and helpers for ComputerCraft TypeScript projects. Think of it as your trusty toolbelt for building awesome CC programs!

📦 Installation

bun add @cc-ts/helpers
# or
npm install @cc-ts/helpers
# or
yarn add @cc-ts/helpers

🎯 Core Utilities

Scheduler (`scheduler.ts`) ⏰

Promise-based event handling and scheduling for ComputerCraft. Perfect for building responsive applications!

import { runOsEventLoop, asyncSleep, on } from "@cc-ts/helpers/scheduler";

// Handle events with type safety
on("mouse_click", (button, x, y) => {
    print(`Click at ${x},${y}`);
});

// Use modern async/await
async function main() {
    print("Starting task...");
    await asyncSleep(1000); // Wait 1 second
    print("Task complete!");
}

// Run your program
void main();
runOsEventLoop();

Learn more about Scheduler

CLI Parser (`cli-parser.ts`) 🎯

Build professional command-line interfaces with ease. Includes support for commands, subcommands, options, and help text.

import {
    parseCliArgs,
    Command,
    executeCommand,
} from "@cc-ts/helpers/cli-parser";

const commands: Command[] = [
    {
        name: "backup",
        description: "💾 Backup computer files",
        options: [
            {
                name: "destination",
                description: "Backup destination",
                defaultValue: "disk",
            },
        ],
        subcommands: [
            {
                name: "list",
                description: "📋 List available backups",
                action: (args) => {
                    print(`Listing backups in ${args.destination}`);
                },
            },
        ],
    },
];

executeCommand(parseCliArgs([...process.argv]), commands);

Learn more about CLI Parser

Sandcorn (`sandcorn.ts`) 🌽

Distributed unique ID generation for ComputerCraft - like Snowflake, but for sand computers! Perfect for distributed systems.

import {
    createSandcornGenerator,
    decodeSandcorn,
} from "@cc-ts/helpers/sandcorn";

const generateId = createSandcornGenerator();

// Generate a unique, time-sortable ID
const id = generateId();

// Decode to see components
const { tick, machineId, seq } = decodeSandcorn(id);
print(`ID from computer ${machineId} at hour ${tick}`);

Learn more about Sandcorn

Persisted Storage (`persisted.ts`) 💾

Simple but powerful persistent storage with type safety. Never lose data between restarts!

import { PersistedStore } from "@cc-ts/helpers/persisted";

// Create a typed store
interface GameState {
    highScore: number;
    lastPlayer: string;
}

const gameState = new PersistedStore<GameState>("game", {
    highScore: 0,
    lastPlayer: "",
});

// Load existing data
gameState.load();

// Update and auto-save
gameState.value.highScore = 1000;
gameState.save();

Learn more about Persisted Storage

Proxy (`proxy.ts`) 🎭

Intercept and customize object behavior - great for debugging, validation, or creating virtual properties.

import { createProxy } from "@cc-ts/helpers/proxy";

// Create a logging proxy for a turtle
const turtle = createProxy(peripheral.find("turtle"), {
    get: (obj, key) => {
        print(`🐢 Turtle ${key} called`);
        return obj[key];
    },
});

Learn more about Proxy

AbortController (`abortController.ts`) 🚦

Cancel async operations gracefully - essential for building responsive applications.

import { AbortController } from "@cc-ts/helpers/abortController";

async function mineShaft(signal: AbortSignal) {
    while (true) {
        signal.throwIfAborted();
        await turtle.digDown();
        await sleep(100);
    }
}

const controller = new AbortController();

// Start mining
void mineShaft(controller.signal);

// Stop if we hit diamond
events.on("diamond_detected", () => {
    controller.abort("Diamond found!");
});

Learn more about AbortController