NLdoc Document Specification Types

TypeScript type definitions and validation schemas for the NLdoc Document Specification. This library provides runtime type validation using Zod schemas, ensuring type safety for document processing and validation.

Overview

This package provides:

• Type Definitions: Complete TypeScript types for all NLdoc document resources
• Runtime Validation: Zod schemas for validating document structures at runtime
• Test Utilities: Helpers for testing document validation and processing
• Resource Types: Comprehensive types for all document elements (Document, Asset, Footnote, etc.)

The types are designed to work seamlessly with the NLdoc Document Specification and provide both compile-time type safety and runtime validation capabilities.

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/types

Or using yarn:

yarn add @nldoc/types

Basic Usage

import { Document, Asset, Footnote } from '@nldoc/types';

// Type-safe document creation
const document: Document = {
  type: 'Document',
  // ... other document properties
};

// Runtime validation
try {
  const validatedDocument = await Document.parseAsync(documentData);
  console.log('Document is valid:', validatedDocument);
} catch (error) {
  console.error('Validation failed:', error);
}

Runtime Validation

The package exports Zod schemas for runtime validation:

import { Document } from '@nldoc/types';

// Validate and parse document data
const result = Document.safeParse(documentData);

if (result.success) {
  // TypeScript knows result.data is a valid Document
  console.log('Valid document:', result.data);
} else {
  // Handle validation errors
  console.error('Validation errors:', result.error.issues);
}

Development

Local Setup

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Available Scripts

• npm run test - Run the test suite with Vitest and coverage
• npm run test:watch - Run tests in watch mode with coverage
• npm run build - Compile TypeScript to JavaScript
• npm run build:check - Type check without emitting files
• 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
• npm run commit - Use conventional commits with Commitizen

Type Definitions

The package exports TypeScript types for all NLdoc document resources:

Core Resources

• Document: The root document container
• Asset: External resources (images, files, etc.)
• Footnote: Document footnotes and references

Text Elements

• Heading: Document headings (H1-H6)
• Paragraph: Text paragraphs with inline content
• Text: Plain text content
• Link: Hyperlinks

Structural Elements

• Table: Tables with headers, rows, and cells
• OrderedList/UnorderedList: Numbered and bulleted lists
• DefinitionList: Term-definition pairs
• BlockQuotation: Quoted content blocks
• Preformatted: Pre-formatted text blocks

Media Elements

• Image: Image resources with metadata

Writing New Types

When adding new types, they should be added to src/resources.ts. All types are contained in one file because some have recursive dependencies on others, which prevents breaking them into separate files while maintaining proper import relationships.

See Zod's documentation on recursive types for more information.

Testing

The types are tested against a comprehensive collection of valid and invalid examples from the NLdoc document specification. Test examples are automatically downloaded on first test run.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

Tests validate:

• Type correctness for valid document examples
• Proper rejection of invalid document structures
• Schema validation accuracy
• Cross-reference integrity

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. Type checking passes (npm run build:check)
5. Use conventional commits (npm run commit)

License

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

Related Packages

• @nldoc/document-specification - OpenAPI 3.1.0 specification
• @nldoc/document-validation-specification - Validation rules

Acknowledgements

• Built with Zod for runtime validation
• Follows OpenAPI 3.1.0 specification standards
• Integrates with Schema.org standards