@nldoc/event-types

NLdoc Event Types

TypeScript type definitions for NLdoc events. This library provides Zod schemas and TypeScript types for validating and working with NLdoc event data, ensuring type safety and runtime validation for event-driven document processing workflows.

Overview

This package defines standardized event types for the NLdoc document processing system:

• QueuedEvent: Indicates a document has been queued for processing
• ProgressEvent: Reports processing progress (pages or documents)
• DoneEvent: Signals successful completion with result location
• ErrorEvent: Handles various error scenarios with detailed context

All events include common fields (timestamp, traceId) and are validated using Zod schemas for both compile-time type safety and runtime validation.

Getting Started

Prerequisites

• Node.js >= 22.0.0 < 23.0.0
• npm >= 10.0.0 < 12.0.0

Installation

Install the package via npm:

npm install @nldoc/event-types

Or using yarn:

yarn add @nldoc/event-types

Basic Usage

import {
  DoneEvent,
  ProgressEvent,
  ErrorEvent,
  Event,
  EventType
} from '@nldoc/event-types';

// Parse and validate a done event
const rawEvent = {
  timestamp: "2024-01-15T10:30:00Z",
  traceId: "abc123",
  type: "https://event.spec.nldoc.nl/done",
  context: {
    contentType: "application/pdf",
    location: "https://storage.example.com/document.pdf"
  }
};

try {
  const typedEvent: DoneEvent = await DoneEvent.parseAsync(rawEvent);
  console.log("Document processed successfully:", typedEvent.context.location);
} catch (error) {
  console.error("Invalid event format:", error);
}

// Handle different event types
async function handleEvent(eventData: unknown) {
  const event = await Event.parseAsync(eventData);

  switch (event.type) {
    case EventType.QUEUED:
      console.log("Document queued for processing");
      break;
    case EventType.PROGRESS:
      console.log(`Progress: ${event.context.position}/${event.context.target} ${event.context.subject}s`);
      break;
    case EventType.DONE:
      console.log("Processing complete:", event.context.location);
      break;
    case EventType.ERROR:
      console.error("Processing error:", event.context);
      break;
  }
}

Event Types

Core Events

QueuedEvent

Indicates a document has been queued for processing.

{
  timestamp: string;     // ISO 8601 datetime
  traceId: string;       // Unique trace identifier
  type: "https://event.spec.nldoc.nl/queued";
  context: {};           // Empty context object
}

ProgressEvent

Reports processing progress for pages or documents.

{
  timestamp: string;
  traceId: string;
  type: "https://event.spec.nldoc.nl/progress";
  context: {
    subject: "page" | "document";  // What is being processed
    target: number;                // Total number to process
    position: number;              // Current position
  };
}

DoneEvent

Signals successful completion with result information.

{
  timestamp: string;
  traceId: string;
  type: "https://event.spec.nldoc.nl/done";
  context: {
    contentType: string;  // MIME type of the result
    location: string;     // URL where result can be accessed
  };
}

ErrorEvent

Handles various error scenarios with detailed context.

{
  timestamp: string;
  traceId: string;
  type: "https://event.spec.nldoc.nl/error";
  context: ErrorContext;  // Discriminated union of error types
}

Error Types

The ErrorContext supports multiple error scenarios:

• invalid_content_type: Wrong content type provided
• too_many_pages: Document exceeds page limit
• unexpected: Unexpected processing error

Development

Local Setup

• Clone the repository:

  git clone https://gitlab.com/logius/nldoc/lib/typescript/event-types.git
  cd event-types
  

• Install dependencies:

  npm install
  

• Build the project:

  npm run build
  

Available Scripts

• npm test - Run the test suite with Vitest and coverage
• npm run test:watch - Run tests in watch mode
• npm run build - Compile TypeScript to JavaScript
• npm run build:check - Type-check without building
• npm run lint - Lint the codebase using ESLint
• npm run format - Format code using Prettier
• npm run format:check - Check code formatting
• npm run fix - Auto-fix linting and formatting issues

Project Structure

The project is organized as follows:

• src/: Contains the TypeScript source files
  • src/__test__/: Test helpers and utilities
  • src/**/*.spec.ts: Test files
  • src/events.ts: Main event type definitions
  • src/index.ts: Package exports
• dist/: Compiled JavaScript output

Writing New Types

When adding new event types:

• Define the event schema in src/events.ts
• Add the event type to the EventType enum
• Include it in the discriminated Event union
• Add comprehensive tests
• Update documentation

Testing

The types are tested against valid and invalid examples from the NLdoc event specification. Test data is automatically downloaded on first run.

Run the test suite:

npm test

The tests validate:

• Schema correctness against specification examples
• Type inference accuracy
• Runtime validation behavior
• Error handling scenarios

API Documentation

Exported Types

• Event - Union type of all event types
• QueuedEvent, DoneEvent, ProgressEvent, ErrorEvent - Individual event types
• ErrorContext - Discriminated union of error contexts
• EventType - Enum of event type URLs

Exported Schemas

All types include corresponding Zod schemas for runtime validation:

• Event.parseAsync() - Validate any event
• DoneEvent.parseAsync() - Validate done events
• etc.

Contributing

We welcome contributions! Please ensure:

• All tests pass (npm test)
• Code is properly formatted (npm run format:check)
• Linting rules are followed (npm run lint)
• Types are properly exported and documented

License

This project is licensed under the European Union Public License 1.2 - see LICENSE for details.

Acknowledgements

• Built with Zod for schema validation