@nldoc/event-types - npm Package Compare versions

Comparing version 2.0.67 to 2.0.68

package.json

 {
     "name": "@nldoc/event-types",
-    "version": "2.0.67",
+    "version": "2.0.68",
     "description": "NLdoc's Type Definitions for Events",
@@ -36,3 +36,3 @@ "author": "NLdoc",
         "cz-conventional-changelog": "^3.3.0",
-        "typescript": "^5.5.4",
+        "typescript": "^5.9.2",
         "vitest": "^3.0.0"
@@ -39,0 +39,0 @@ },

README.md

@@ -1,15 +0,32 @@
-# NLdoc Event Specification Types
+# NLdoc Event Types
 
-This repository contains the event specification types for the NLdoc project.
+[![pipeline status](https://gitlab.com/logius/nldoc/lib/typescript/event-types/badges/main/pipeline.svg)](https://gitlab.com/logius/nldoc/lib/typescript/event-types/-/commits/main)
+[![coverage report](https://gitlab.com/logius/nldoc/lib/typescript/event-types/badges/main/coverage.svg?job=test)](https://gitlab.com/logius/nldoc/lib/typescript/event-types/-/commits/main)
+[![Latest Release](https://gitlab.com/logius/nldoc/lib/typescript/event-types/-/badges/release.svg)](https://gitlab.com/logius/nldoc/lib/typescript/event-types/-/releases)
+[![NPM Version](https://img.shields.io/npm/v/@nldoc/event-types)](https://www.npmjs.com/package/@nldoc/event-types)
 
-## Installation
+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.
 
-Add to your `.npmrc` file:
+## Overview
 
-```.npmrc
-@nldoc:registry=https://gitlab.com/api/v4/packages/npm/
-```
+This package defines standardized event types for the NLdoc document processing system:
 
-Then run:
+- **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:
+
 ```bash
@@ -19,38 +36,227 @@ npm install @nldoc/event-types
 
-## Usage
+Or using yarn:
 
+```bash
+yarn add @nldoc/event-types
+```
+
+### Basic Usage
+
 ```typescript
-import { DoneEvent } from '@nldoc/event-types'
+import {
+  DoneEvent,
+  ProgressEvent,
+  ErrorEvent,
+  Event,
+  EventType
+} from '@nldoc/event-types';
 
-const typedEvent: DoneEvent = await DoneEvent.parseAsync(event)
+// 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.
+
+```typescript
+{
+  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.
+
+```typescript
+{
+  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.
+
+```typescript
+{
+  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.
+
+```typescript
+{
+  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
 
-### Project structure
+### Local Setup
 
-The project is structured as follows:
+1. Clone the repository:
 
-- `src/`: Contains the TypeScript source files.
-    - `src/__test__/`: Contains the test helpers for the TypeScript source files.
-    - `src/**/*.spec.ts`: Contains the tests for the TypeScript source files.
-    - `src/events.ts`: Contains the Event types as documented in the Specification.
-- `dist/`: Contains the compiled JavaScript files.
+   ```bash
+   git clone https://gitlab.com/logius/nldoc/lib/typescript/event-types.git
+   cd event-types
+   ```
 
-### Writing new types
+2. Install dependencies:
 
-When writing new types, they would go into `src/events.ts`.
+   ```bash
+   npm install
+   ```
 
+3. Build the project:
+
+   ```bash
+   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:
+
+1. Define the event schema in `src/events.ts`
+2. Add the event type to the `EventType` enum
+3. Include it in the discriminated `Event` union
+4. Add comprehensive tests
+5. Update documentation
+
 ### Testing
 
-The types in this package are tested against the collection of examples (valid and invalid) that were provided in the NLdoc event specification. These examples will be downloaded to the local filesystem on first run of the tests.
+The types are tested against valid and invalid examples from the NLdoc event specification. Test data is automatically downloaded on first run.
 
-To run the tests, run:
+Run the test suite:
 
 ```bash
-$ npm test
+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:
+
+1. All tests pass (`npm test`)
+2. Code is properly formatted (`npm run format:check`)
+3. Linting rules are followed (`npm run lint`)
+4. Types are properly exported and documented
+
 ## License
 
-See [LICENSE.txt](LICENSE.txt) for the license of this repository.
+This project is licensed under the European Union Public License 1.2 - see [LICENSE](LICENSE) for details.
+
+## Acknowledgements
+
+- Built with [Zod](https://zod.dev/) for schema validation

No alert changes

Improved metrics

Total package byte prevSize

31009

22.38%

Number of lines in readme file

262

367.86%

No dependency changes