@nldoc/types - npm Package Compare versions

Comparing version 4.0.60 to 4.0.61

dist/util/Resource.d.ts

@@ -12,8 +12,5 @@ import { z } from 'zod';
     type: z.ZodLiteral<`https://spec.nldoc.nl/Resource/${T}`>;
-} & Y extends infer T_1 ? { -readonly [P in keyof T_1]: ({
+} & Y extends infer T_1 ? { -readonly [P in keyof T_1]: T_1[P]; } : never) | {
     id: z.ZodUUID;
     type: z.ZodLiteral<`https://spec.nldoc.nl/Resource/${T}`>;
-} & Y)[P]; } : never) | {
-    id: z.ZodUUID;
-    type: z.ZodLiteral<`https://spec.nldoc.nl/Resource/${T}`>;
 }, z.core.$strict>;

package.json

 {
     "name": "@nldoc/types",
-    "version": "4.0.60",
+    "version": "4.0.61",
     "description": "NLdoc's Type Definitions for Document Specification",
@@ -37,3 +37,3 @@ "author": "NLdoc",
         "cz-conventional-changelog": "^3.3.0",
-        "typescript": "^5.5.4",
+        "typescript": "^5.9.2",
         "vitest": "^3.0.0"
@@ -40,0 +40,0 @@ },

README.md

 # NLdoc Document Specification Types
 
-This repository contains the document specification types for the NLdoc project.
+[![pipeline status](https://gitlab.com/logius/nldoc/lib/typescript/types/badges/main/pipeline.svg)](https://gitlab.com/logius/nldoc/lib/typescript/types/-/commits/main)
+[![coverage report](https://gitlab.com/logius/nldoc/lib/typescript/types/badges/main/coverage.svg?job=test)](https://gitlab.com/logius/nldoc/lib/typescript/types/-/commits/main)
+[![Latest Release](https://gitlab.com/logius/nldoc/lib/typescript/types/-/badges/release.svg)](https://gitlab.com/logius/nldoc/lib/typescript/types/-/releases)
+[![NPM Version](https://img.shields.io/npm/v/@nldoc/types)](https://www.npmjs.com/package/@nldoc/types)
 
-## Installation
+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.
 
-Add to your `.npmrc` file:
+## Overview
 
-```.npmrc
-@nldoc:registry=https://gitlab.com/api/v4/packages/npm/
+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](https://gitlab.com/logius/nldoc/spec/document) 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:
+
+```bash
+npm install @nldoc/types
 ```
 
-Then run:
+Or using yarn:
 
 ```bash
-npm install @nldoc/nldoc-document-specification-types
+yarn add @nldoc/types
 ```
 
-## Usage
+### Basic Usage
 
 ```typescript
-import { Document } from '@nldoc/nldoc-document-specification-types';
+import { Document, Asset, Footnote } from '@nldoc/types';
 
-const typedDocument: Document = await Document.parseAsync(document);
+// 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:
+
+```typescript
+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
 
-### 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/properties/`: Contains commonly used properties for the document specification types.
-    - `src/util/`: Contains utility functions for building up the types.
-    - `src/resources.ts`: Contains the Resource types as documented in the Specification.
-    - `src/descriptors.ts`: Contains the Descriptor Resource types as documented in the
-      Specification.
-- `dist/`: Contains the compiled JavaScript files.
+   ```bash
+   git clone https://gitlab.com/logius/nldoc/lib/typescript/types.git
+   cd types
+   ```
 
-### Writing new types
+2. Install dependencies:
 
-When writing new types, they would go into `src/resources.ts`.
+   ```bash
+   npm install
+   ```
 
-These types are inside one file, because some of them are recursively dependent on others. This
-prevents us from breaking up the types into separate files, as imports would break the recursive
-dependencies.
+3. Build the project:
 
-[See Zod's documentation for more information.](https://zod.dev/?id=recursive-types)
+   ```bash
+   npm run build
+   ```
 
-### Testing
+### Available Scripts
 
-The types in this package are tested against the collection of examples (valid and invalid) that
-were provided in the NLdoc document specification. These examples will be downloaded to the local
-filesystem on first run of the tests.
+- `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
 
-To run the tests, run:
+## 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](https://zod.dev/?id=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.
+
 ```bash
-$ npm test
+# 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
 
-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.
+
+## Related Packages
+
+- [@nldoc/document-specification](https://www.npmjs.com/package/@nldoc/document-specification) - OpenAPI 3.1.0 specification
+- [@nldoc/document-validation-specification](https://www.npmjs.com/package/@nldoc/document-validation-specification) - Validation rules
+
+## Acknowledgements
+
+- Built with [Zod](https://zod.dev/) for runtime validation
+- Follows [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0) specification standards
+- Integrates with [Schema.org](https://schema.org/) standards

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

433550

0.9%

Number of lines in readme file

188

176.47%

Worsened metrics

Lines of code

8095

-0.04%

No dependency changes