CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-lumino--coreutils

Essential utility functions and classes for TypeScript/JavaScript applications including JSON handling, MIME data management, promise delegation, secure tokens, and cross-platform random number generation.

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

token-system.mddocs/

Token System

Runtime tokens that capture compile-time type information for type-safe object identity and dependency injection systems. Tokens provide a way to create unique identifiers that maintain type safety at runtime.

Capabilities

Token Class

A runtime object which captures compile-time type information, allowing type-safe identification and dependency injection.

/**
 * A runtime object which captures compile-time type information.
 * 
 * Notes:
 * A token captures the compile-time type of an interface or class in
 * an object which can be used at runtime in a type-safe fashion.
 */
class Token<T> {
  /**
   * Construct a new token
   * @param name - A human readable name for the token
   */
  constructor(name: string);

  /**
   * The human readable name for the token.
   * 
   * Notes:
   * This can be useful for debugging and logging.
   */
  readonly name: string;
}

Usage Examples:

import { Token } from "@lumino/coreutils";

// Define interfaces for your types
interface User {
  id: number;
  name: string;
  email: string;
}

interface Config {
  apiUrl: string;
  theme: string;
  debug: boolean;
}

interface Logger {
  log(message: string): void;
  error(message: string): void;
}

// Create tokens for each type
const UserToken = new Token<User>("user");
const ConfigToken = new Token<Config>("config");
const LoggerToken = new Token<Logger>("logger");

// Tokens can be used for type-safe identification
console.log(UserToken.name); // "user"
console.log(ConfigToken.name); // "config"
console.log(LoggerToken.name); // "logger"

// Each token is unique, even with the same name
const AnotherUserToken = new Token<User>("user");
console.log(UserToken === AnotherUserToken); // false

Common Use Cases

Dependency Injection:

import { Token } from "@lumino/coreutils";

// Define service interfaces
interface DatabaseService {
  query(sql: string): Promise<any[]>;
  save(entity: any): Promise<void>;
}

interface EmailService {
  sendEmail(to: string, subject: string, body: string): Promise<void>;
}

interface UserService {
  getUser(id: number): Promise<User>;
  createUser(userData: Partial<User>): Promise<User>;
}

// Create tokens for services
const DatabaseToken = new Token<DatabaseService>("database");
const EmailToken = new Token<EmailService>("email");
const UserServiceToken = new Token<UserService>("user-service");

// Simple dependency injection container
class Container {
  private services = new Map<Token<any>, any>();

  register<T>(token: Token<T>, implementation: T): void {
    this.services.set(token, implementation);
  }

  resolve<T>(token: Token<T>): T {
    const service = this.services.get(token);
    if (!service) {
      throw new Error(`Service not found for token: ${token.name}`);
    }
    return service;
  }
}

// Usage
const container = new Container();

// Register services
container.register(DatabaseToken, new SqliteDatabase());
container.register(EmailToken, new SmtpEmailService());
container.register(UserServiceToken, new UserServiceImpl(
  container.resolve(DatabaseToken),
  container.resolve(EmailToken)
));

// Resolve services with type safety
const userService = container.resolve(UserServiceToken); // Type is UserService
const user = await userService.getUser(123);

Plugin System:

import { Token } from "@lumino/coreutils";

// Define plugin interfaces
interface Plugin {
  name: string;
  version: string;
  activate(app: Application): void;
  deactivate(): void;
}

interface ThemePlugin extends Plugin {
  getThemes(): Theme[];
  applyTheme(themeName: string): void;
}

interface EditorPlugin extends Plugin {
  createEditor(element: HTMLElement): Editor;
}

// Create tokens for different plugin types
const ThemePluginToken = new Token<ThemePlugin>("theme-plugin");
const EditorPluginToken = new Token<EditorPlugin>("editor-plugin");

// Plugin registry
class PluginRegistry {
  private plugins = new Map<Token<any>, Plugin[]>();

  registerPlugin<T extends Plugin>(token: Token<T>, plugin: T): void {
    if (!this.plugins.has(token)) {
      this.plugins.set(token, []);
    }
    this.plugins.get(token)!.push(plugin);
  }

  getPlugins<T extends Plugin>(token: Token<T>): T[] {
    return (this.plugins.get(token) || []) as T[];
  }

  getPlugin<T extends Plugin>(token: Token<T>, name: string): T | undefined {
    const plugins = this.getPlugins(token);
    return plugins.find(p => p.name === name) as T | undefined;
  }
}

// Usage
const registry = new PluginRegistry();

// Register plugins
registry.registerPlugin(ThemePluginToken, new DarkThemePlugin());
registry.registerPlugin(ThemePluginToken, new LightThemePlugin());
registry.registerPlugin(EditorPluginToken, new MonacoEditorPlugin());

// Get plugins with type safety
const themePlugins = registry.getPlugins(ThemePluginToken); // Type is ThemePlugin[]
const darkTheme = registry.getPlugin(ThemePluginToken, "dark-theme"); // Type is ThemePlugin | undefined

Event System with Type Safety:

import { Token } from "@lumino/coreutils";

// Define event payload types
interface UserLoginEvent {
  userId: number;
  timestamp: Date;
  source: string;
}

interface FileUploadEvent {
  filename: string;
  size: number;
  mimeType: string;
}

interface SystemErrorEvent {
  error: Error;
  context: string;
  severity: "low" | "medium" | "high" | "critical";
}

// Create tokens for each event type
const UserLoginToken = new Token<UserLoginEvent>("user-login");
const FileUploadToken = new Token<FileUploadEvent>("file-upload");
const SystemErrorToken = new Token<SystemErrorEvent>("system-error");

// Type-safe event emitter
class TypedEventEmitter {
  private listeners = new Map<Token<any>, Function[]>();

  on<T>(token: Token<T>, listener: (event: T) => void): void {
    if (!this.listeners.has(token)) {
      this.listeners.set(token, []);
    }
    this.listeners.get(token)!.push(listener);
  }

  emit<T>(token: Token<T>, event: T): void {
    const eventListeners = this.listeners.get(token) || [];
    eventListeners.forEach(listener => listener(event));
  }

  off<T>(token: Token<T>, listener: (event: T) => void): void {
    const eventListeners = this.listeners.get(token) || [];
    const index = eventListeners.indexOf(listener);
    if (index !== -1) {
      eventListeners.splice(index, 1);
    }
  }
}

// Usage
const eventEmitter = new TypedEventEmitter();

// Register type-safe listeners
eventEmitter.on(UserLoginToken, (event) => {
  // event is typed as UserLoginEvent
  console.log(`User ${event.userId} logged in from ${event.source}`);
});

eventEmitter.on(FileUploadToken, (event) => {
  // event is typed as FileUploadEvent
  console.log(`File uploaded: ${event.filename} (${event.size} bytes)`);
});

eventEmitter.on(SystemErrorToken, (event) => {
  // event is typed as SystemErrorEvent
  if (event.severity === "critical") {
    console.error(`Critical error in ${event.context}:`, event.error);
  }
});

// Emit events with type safety
eventEmitter.emit(UserLoginToken, {
  userId: 123,
  timestamp: new Date(),
  source: "web"
});

eventEmitter.emit(FileUploadToken, {
  filename: "document.pdf",
  size: 1024000,
  mimeType: "application/pdf"
});

Configuration Management:

import { Token } from "@lumino/coreutils";

// Define configuration interfaces
interface DatabaseConfig {
  host: string;
  port: number;
  database: string;
  username: string;
  password: string;
}

interface ApiConfig {
  baseUrl: string;
  timeout: number;
  apiKey: string;
}

interface UiConfig {
  theme: "light" | "dark";
  language: string;
  animations: boolean;
}

// Create configuration tokens
const DatabaseConfigToken = new Token<DatabaseConfig>("database-config");
const ApiConfigToken = new Token<ApiConfig>("api-config");
const UiConfigToken = new Token<UiConfig>("ui-config");

// Configuration manager
class ConfigManager {
  private configs = new Map<Token<any>, any>();

  set<T>(token: Token<T>, config: T): void {
    this.configs.set(token, config);
  }

  get<T>(token: Token<T>): T {
    const config = this.configs.get(token);
    if (!config) {
      throw new Error(`Configuration not found for: ${token.name}`);
    }
    return config;
  }

  has<T>(token: Token<T>): boolean {
    return this.configs.has(token);
  }
}

// Usage
const configManager = new ConfigManager();

// Set configurations
configManager.set(DatabaseConfigToken, {
  host: "localhost",
  port: 5432,
  database: "myapp",
  username: "user",
  password: "password"
});

configManager.set(ApiConfigToken, {
  baseUrl: "https://api.example.com",
  timeout: 5000,
  apiKey: "secret-key"
});

// Get configurations with type safety
const dbConfig = configManager.get(DatabaseConfigToken); // Type is DatabaseConfig
const apiConfig = configManager.get(ApiConfigToken); // Type is ApiConfig

console.log(`Connecting to database at ${dbConfig.host}:${dbConfig.port}`);
console.log(`API base URL: ${apiConfig.baseUrl}`);

docs

index.md

json-utilities.md

mime-data.md

promise-delegation.md

random-generation.md

token-system.md

uuid-generation.md

tile.json