Register a checkpoint with a callback
Creates a new checkpoint with an initial callback handler. If a checkpoint with the same name already exists, it is completely replaced (including all callbacks and metadata). Use addCallback() to add additional handlers to an existing checkpoint without replacing it.
Validation:
Unique name identifier for the checkpoint (e.g., 'tests_complete')
Callback function to execute when checkpoint is triggered
Optionalmetadata: CheckpointMetadataOptional metadata providing context about the checkpoint
True if checkpoint registered successfully, false if validation fails
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register basic checkpoint
const success = detector.registerCheckpoint(
'tests_complete',
async (data) => {
console.log(`All tests passed: ${data.testCount}`);
return { success: true };
}
);
console.log(`Registered: ${success}`); // true
// Register with metadata
detector.registerCheckpoint(
'build_complete',
async (data) => {
await deployToStaging(data.buildArtifacts);
return { success: true };
},
{
description: 'Deploy to staging after successful build',
priority: 'high',
category: 'deployment'
}
);
// Validation examples
const invalid1 = detector.registerCheckpoint('', async () => ({ success: true }));
console.log(invalid1); // false - empty name
const invalid2 = detector.registerCheckpoint('valid_name', null as any);
console.log(invalid2); // false - null callback
Add an additional callback to an existing checkpoint
Appends a new callback handler to an existing checkpoint without affecting existing callbacks or metadata. All callbacks execute sequentially in the order they were added when the checkpoint is triggered.
Use Case: Add multiple independent actions to the same checkpoint event, such as code review + coverage report + notification when tests complete.
Name of the existing checkpoint to add callback to
Additional callback function to execute on checkpoint trigger
True if callback added successfully, false if checkpoint not found
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register initial checkpoint
detector.registerCheckpoint(
'tests_complete',
async (data) => {
console.log(`Tests passed: ${data.testCount}`);
return { success: true };
}
);
// Add coverage report callback
detector.addCallback('tests_complete', async (data) => {
await updateCoverageReport(data.coverage);
return { success: true };
});
// Add notification callback
detector.addCallback('tests_complete', async (data) => {
await sendSlackNotification('Tests completed successfully!');
return { success: true };
});
// All 3 callbacks execute when checkpoint triggered
await detector.triggerCheckpoint('tests_complete', {
testCount: 42,
coverage: 0.95
});
// Returns false if checkpoint doesn't exist
const failed = detector.addCallback('nonexistent', async () => ({ success: true }));
console.log(failed); // false
Check if a checkpoint is registered
Verifies whether a checkpoint exists in the registry. Use this to conditionally register, trigger, or add callbacks to checkpoints.
Name of the checkpoint to check for existence
True if checkpoint is registered, false otherwise
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register a checkpoint
detector.registerCheckpoint(
'tests_complete',
async () => ({ success: true })
);
// Check if registered
if (detector.isCheckpointRegistered('tests_complete')) {
console.log('Checkpoint exists, can trigger');
await detector.triggerCheckpoint('tests_complete', {});
}
// Conditional registration
if (!detector.isCheckpointRegistered('build_complete')) {
detector.registerCheckpoint(
'build_complete',
async (data) => {
console.log('Build completed');
return { success: true };
}
);
}
// Check non-existent checkpoint
const exists = detector.isCheckpointRegistered('nonexistent');
console.log(exists); // false
Get list of all registered checkpoints
Returns an array of all checkpoint names currently registered in the detector. Useful for debugging, introspection, and displaying available checkpoints.
Array of checkpoint names (strings) in insertion order
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register multiple checkpoints
detector.registerCheckpoint('tests_complete', async () => ({ success: true }));
detector.registerCheckpoint('build_complete', async () => ({ success: true }));
detector.registerCheckpoint('deploy_complete', async () => ({ success: true }));
// Get all registered checkpoints
const checkpoints = detector.getRegisteredCheckpoints();
console.log(checkpoints); // ['tests_complete', 'build_complete', 'deploy_complete']
// Display available checkpoints
console.log('Available checkpoints:');
detector.getRegisteredCheckpoints().forEach(name => {
const metadata = detector.getCheckpointMetadata(name);
console.log(` - ${name}: ${metadata?.description || 'No description'}`);
});
// Check count
const count = detector.getRegisteredCheckpoints().length;
console.log(`Total checkpoints: ${count}`);
Trigger a checkpoint, executing all registered callbacks
Executes all callbacks registered for the specified checkpoint sequentially. Implements graceful failure handling: continues executing remaining callbacks even if some fail. Returns success if at least one callback succeeds.
Execution Behavior:
{ triggered: true, failedCallbacks: undefined }{ triggered: true, failedCallbacks: N }{ triggered: false, error: "first error message" }Callback execution is sequential (not parallel) in the order callbacks were registered. This ensures predictable execution order and allows callbacks to depend on previous ones.
Name of the checkpoint to trigger (must be registered)
Event data passed to all callbacks (available as callback parameter)
Promise
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register checkpoint with multiple callbacks
detector.registerCheckpoint(
'tests_complete',
async (data) => {
console.log(`Tests passed: ${data.testCount}`);
return { success: true };
}
);
detector.addCallback('tests_complete', async (data) => {
await updateCoverageReport(data.coverage);
return { success: true };
});
detector.addCallback('tests_complete', async (data) => {
// This callback might fail
if (Math.random() < 0.5) {
throw new Error('Notification service unavailable');
}
await sendNotification('Tests complete!');
return { success: true };
});
// Trigger checkpoint
const result = await detector.triggerCheckpoint('tests_complete', {
testCount: 42,
coverage: 0.95,
duration: 15.3
});
if (result.triggered) {
console.log('Checkpoint executed successfully');
if (result.failedCallbacks) {
console.warn(`${result.failedCallbacks} callback(s) failed`);
}
} else {
console.error(`All callbacks failed: ${result.error}`);
}
// Handle non-existent checkpoint
try {
await detector.triggerCheckpoint('nonexistent', {});
} catch (error) {
if (error instanceof NotFoundError) {
console.error('Checkpoint not registered');
}
}
Unregister a checkpoint
Completely removes a checkpoint from the registry, including all callbacks and metadata. Use this to clean up checkpoints that are no longer needed.
Name of the checkpoint to remove from registry
True if checkpoint existed and was removed, false if not found
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register a temporary checkpoint
detector.registerCheckpoint(
'temp_checkpoint',
async () => ({ success: true })
);
// Use the checkpoint
await detector.triggerCheckpoint('temp_checkpoint', {});
// Remove when no longer needed
const removed = detector.unregisterCheckpoint('temp_checkpoint');
console.log(removed); // true
// Verify removed
const exists = detector.isCheckpointRegistered('temp_checkpoint');
console.log(exists); // false
// Removing non-existent checkpoint returns false
const notFound = detector.unregisterCheckpoint('nonexistent');
console.log(notFound); // false
// Clean up all checkpoints
detector.getRegisteredCheckpoints().forEach(name => {
detector.unregisterCheckpoint(name);
});
console.log(detector.getRegisteredCheckpoints().length); // 0
Get metadata for a specific checkpoint
Retrieves the optional metadata associated with a checkpoint. Metadata includes description, priority level, and category information attached during registration. Returns undefined if checkpoint doesn't exist or has no metadata.
Name of the checkpoint to get metadata for
CheckpointMetadata object if exists, undefined if checkpoint not found or has no metadata
import { CheckpointDetector } from './CheckpointDetector.js';
const detector = new CheckpointDetector();
// Register checkpoint with metadata
detector.registerCheckpoint(
'tests_complete',
async () => ({ success: true }),
{
description: 'Trigger code review after tests pass',
priority: 'high',
category: 'testing'
}
);
// Get metadata
const metadata = detector.getCheckpointMetadata('tests_complete');
if (metadata) {
console.log(`Description: ${metadata.description}`);
console.log(`Priority: ${metadata.priority}`);
console.log(`Category: ${metadata.category}`);
}
// Display all checkpoints with metadata
detector.getRegisteredCheckpoints().forEach(name => {
const meta = detector.getCheckpointMetadata(name);
if (meta) {
console.log(`${name}: ${meta.description} [${meta.priority}]`);
} else {
console.log(`${name}: No metadata`);
}
});
// Returns undefined for non-existent checkpoint
const notFound = detector.getCheckpointMetadata('nonexistent');
console.log(notFound); // undefined
// Returns undefined if no metadata provided during registration
detector.registerCheckpoint('no_metadata', async () => ({ success: true }));
const noMeta = detector.getCheckpointMetadata('no_metadata');
console.log(noMeta); // undefined
Checkpoint Detector Class
Manages checkpoint registration and triggering for development workflow events. Supports multiple callbacks per checkpoint and graceful error handling.