or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context-management.mdindex.mdplugin-orchestration.mdruntime-inspection.mdtimer-coordination.md
tile.json

tessl/npm-milkdown--ctx

Core context management module for Milkdown editor providing dependency injection and state management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@milkdown/ctx@7.15.x

To install, run

npx @tessl/cli install tessl/npm-milkdown--ctx@7.15.0

index.mddocs/

@milkdown/ctx

@milkdown/ctx is the core context management module for the Milkdown editor framework. It provides a sophisticated dependency injection and state management system through Container and Slice patterns, along with timing/scheduling capabilities and comprehensive debugging tools. The package enables plugin-based architecture where components can inject dependencies, manage reactive state, and coordinate through a well-defined context system.

Package Information

  • Package Name: @milkdown/ctx
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @milkdown/ctx

Core Imports

import { 
  Container, 
  Slice, 
  SliceType, 
  createSlice,
  Ctx, 
  Clock, 
  Timer, 
  TimerType, 
  createTimer,
  Inspector,
  type Meta,
  type MilkdownPlugin,
  type Telemetry,
  type TimerStatus
} from "@milkdown/ctx";

For CommonJS:

const { 
  Container, 
  Slice, 
  SliceType, 
  createSlice,
  Ctx, 
  Clock, 
  Timer, 
  TimerType, 
  createTimer,
  Inspector
} = require("@milkdown/ctx");

Basic Usage

import { Container, createSlice, Ctx, Clock } from "@milkdown/ctx";

// Create a container and clock
const container = new Container();
const clock = new Clock();

// Create a slice type for state management  
const counterSlice = createSlice(0, "counter");

// Create context and inject the slice
const ctx = new Ctx(container, clock);
ctx.inject(counterSlice, 5);

// Use the context to access and update state
const currentValue = ctx.get(counterSlice); // 5
ctx.update(counterSlice, (prev) => prev + 1);
console.log(ctx.get(counterSlice)); // 6

// React to state changes
const slice = ctx.use(counterSlice);
const unsubscribe = slice.on((value) => {
  console.log("Counter changed to:", value);
});

Architecture

@milkdown/ctx is built around several key architectural patterns:

  • Container-Slice Pattern: Central container manages typed slices for dependency injection and state management
  • Reactive Updates: Slices support watchers for reactive programming with on/off subscription model
  • Context Orchestration: Ctx class provides unified access to containers and clocks with metadata support
  • Timer Coordination: Clock manages promise-based timers for scheduling and synchronization
  • Inspector Integration: Built-in debugging and telemetry collection for runtime analysis
  • Plugin Architecture: MilkdownPlugin type enables modular extensions with setup/run/cleanup lifecycle

Capabilities

Context Management

Core dependency injection and state management through Container and Slice system. Provides type-safe reactive state with watcher support for building plugin-based architectures.

class Container {
  get<T, N extends string = string>(slice: SliceType<T, N> | N): Slice<T, N>;
  remove<T, N extends string = string>(slice: SliceType<T, N> | N): void;
  has<T, N extends string = string>(slice: SliceType<T, N> | N): boolean;
}

class Slice<T = any, N extends string = string> {
  readonly type: SliceType<T, N>;
  on(watcher: (value: T) => unknown): () => void;
  once(watcher: (value: T) => unknown): () => void;
  off(watcher: (value: T) => unknown): void;
  offAll(): void;
  set(value: T): void;
  get(): T;
  update(updater: (prev: T) => T): void;
}

class SliceType<T = any, N extends string = string> {
  readonly id: symbol;
  readonly name: N;
  constructor(value: T, name: N);
  create(container: SliceMap, value?: T): Slice<T, N>;
}

function createSlice<T = any, N extends string = string>(value: T, name: N): SliceType<T, N>;

Context Management

Plugin Orchestration

Central orchestration class providing unified access to containers, clocks, and debugging capabilities for plugin development and state coordination.

class Ctx {
  readonly meta: Meta | undefined;
  readonly inspector: Inspector | undefined;
  
  constructor(container: Container, clock: Clock, meta?: Meta);
  produce(meta?: Meta): Ctx;
  inject<T>(sliceType: SliceType<T>, value?: T): Ctx;
  remove<T, N extends string = string>(sliceType: SliceType<T, N> | N): Ctx;
  record(timerType: TimerType): Ctx;
  clearTimer(timerType: TimerType): Ctx;
  isInjected<T, N extends string = string>(sliceType: SliceType<T, N> | N): boolean;
  isRecorded(timerType: TimerType): boolean;
  use<T, N extends string = string>(sliceType: SliceType<T, N> | N): Slice<T, N>;
  get<T, N extends string>(sliceType: SliceType<T, N> | N): T;
  set<T, N extends string>(sliceType: SliceType<T, N> | N, value: T): void;
  update<T, N extends string>(sliceType: SliceType<T, N> | N, updater: (prev: T) => T): void;
  timer(timer: TimerType): Timer;
  done(timer: TimerType): void;
  wait(timer: TimerType): Promise<void>;
  waitTimers(slice: SliceType<TimerType[]>): Promise<void>;
}

type MilkdownPlugin = { meta?: Meta } & ((ctx: Ctx) => CtxRunner);

Plugin Orchestration

Timer Coordination

Promise-based timer system with event-driven resolution for scheduling and synchronization in plugin architectures.

class Clock {
  readonly store: TimerMap;
  get(timer: TimerType): Timer;
  remove(timer: TimerType): void;
  has(timer: TimerType): boolean;
}

class Timer {
  readonly type: TimerType;
  readonly status: TimerStatus;
  start(): Promise<void>;
  done(): void;
}

class TimerType {
  readonly id: symbol;
  readonly name: string;
  readonly timeout: number;
  constructor(name: string, timeout?: number);
  create(clock: TimerMap): Timer;
}

function createTimer(name: string, timeout?: number): TimerType;

type TimerStatus = 'pending' | 'resolved' | 'rejected';

Timer Coordination

Runtime Inspection

Debugging and telemetry system for monitoring ctx operations, slice usage, and timer execution in development and production environments.

class Inspector {
  constructor(container: Container, clock: Clock, meta: Meta);
  read(): Telemetry;
}

interface Meta {
  displayName: string;
  description?: string;
  package: string;
  group?: string;
  additional?: Record<string, any>;
}

interface Telemetry {
  metadata: Meta;
  injectedSlices: { name: string; value: unknown }[];
  consumedSlices: { name: string; value: unknown }[];
  recordedTimers: { name: string; duration: number; status: TimerStatus }[];
  waitTimers: { name: string; duration: number; status: TimerStatus }[];
}

Runtime Inspection

Types

type SliceMap = Map<symbol, Slice>;
type TimerMap = Map<symbol, Timer>;
type Cleanup = () => void | Promise<void>;
type RunnerReturnType = void | Promise<void> | Cleanup | Promise<Cleanup>;
type CtxRunner = () => RunnerReturnType;