nuvira-parser v1.0.1

Nuvira

Nuvira is a structured data format that combines schema definitions, validation rules, records, and relationships. It provides a way to define complex data relationships and structures while ensuring data integrity through validation and strict mode enforcement.

Table of Contents

• Overview
• Nuvira File Structure
• File Rules
• Schema Section
• Relations Section
• Validation Section
• Records Section
• Key Features of Nuvira
• Example Usage
  • Nuvira Validation Example
• Advantages of Nuvira Format

Overview

Nuvira File Structure

File Rules (*STRICT, *SIZE, *TYPE, *LOCKED)

2. Schema Section (@schema)

• Number: Represents numerical values.
• String: Represents textual data.
• Binary: Represents binary data.
• Date: Represents date values.
• Boolean: Represents true/false values.
• Uint8Array: Represents an array of unsigned 8-bit integers.
• Object: Represents an object with key-value pairs.
• Any[]: Represents an array of any type of data.
• StringArray: Represents an array of strings.
• String[]: Another way to define an array of strings.
• ObjectArray: Represents an array of objects.
• NumberArray: Represents an array of numbers.
• Number[]: Another way to define an array of numbers.
• Null: Represents a null value (used when a field can be null).
• undefined: Represents an undefined value (used when a field can be undefined).
• Array: A general array type.
• []: Another way to define an array (equivalent to Array).
• Any: Represents any data type (used when the field type is flexible).
• AnyArray: Represents an array of any data type.

3. Relations Section (@relations)

Company(age) -> Users(age) { type = "one-to-one"; onDelete = "cascade"; onUpdate = "restrict"; } @end

4. Validation Section (@validations)

5. Records Section (@records)

Example Usage

Example Usage for Nuvira Validation

// Example Schema Definition const schema: Record<string, SchemaDefinition> = { username: { type: 'String' }, age: { type: 'Number' }, birthdate: { type: 'Date' }, isVerified: { type: 'Boolean' }, friends: { type: 'StringArray' }, preferences: { type: 'Object', properties: { theme: { type: 'String' }, notifications: { type: 'Boolean' } } }, activities: { type: 'ObjectArray', items: {

type: 'String' } } };

// Example Validation Rule const validation: Record<string, ValidationRules> = { username: { required: true, minLength: 3, maxLength: 20, isUnique: true }, age: { required: true, min: 18, max: 99 }, birthdate: { required: true, isDate: true }, isVerified: { required: true }, friends: { minLength: 1 }, preferences: { required: true } };

// Example Validation Request const params: ValidateParams = { username: "JohnDoe", age: 30, birthdate: new Date(), isVerified: true, friends: "Jane", "Doe", preferences: { theme: "dark", notifications: true } };

const validationResult: ValidationResult = Validator.validate(schema, validation, params);

if (validationResult.isValid) { console.log("Validation passed."); } else { console.error("Validation failed."); }

Key Features of Nuvira

• Document Numbers:
  Each record is identified by a unique document number (#0, #1, #2, etc.). These document numbers are essential for referencing specific records, ensuring easy tracking, error resolution, and quick lookups. This helps organize large datasets and allows for efficient querying and validation.

• Indexed Arrays:
  Arrays in Nuvira are indexed with unique keys like _0, _1, _2, etc. This provides clarity and structure for managing array elements and ensures consistency when accessing or modifying individual elements. It is particularly useful for data where elements are ordered and need to be referenced directly.

• Strict Mode:
  The strict mode (*STRICT=TRUE) ensures that the data strictly follows the schema structure, types, and the order of elements. When strict mode is enabled, any deviation from the schema, such as missing fields, wrong data types, or extra fields, will lead to validation errors. In non-strict mode (*STRICT=FALSE), the format allows for more flexible data input and can accommodate deviations from the strict schema, giving you more freedom when working with the data.

• Schema Definition Flexibility:
  The Nuvira format supports various schema types—ROOT, NODE, LEAF, ISOLATED, and REFERENCE—giving users flexibility to define complex relationships between data fields and structure. This ensures that your data models can range from simple flat structures to deeply nested or interconnected schemas.

• Validation Rules:
  Validation is a built-in feature in Nuvira, ensuring that data adheres to predefined rules. Rules can be applied to fields, specifying things like required, minLength, maxLength, isDate, unique, and more. This allows for automatic validation during data insertion or modification, ensuring that the data stays consistent and valid.

• File Integrity:
  The File Rules (*STRICT, *SIZE, *TYPE, *LOCKED) at the top of the Nuvira file define global settings for how the data is structured and validated. These settings also specify whether the schema is locked or can be modified, and how strict the validation should be across the entire file.

• Nested and Complex Data Types:
  Nuvira allows for the definition of complex data types like Objects, Arrays, and even Arrays of Objects, allowing for multi-level data modeling. It’s possible to nest objects within objects, as well as create arrays of multiple types, making it suitable for complex, real-world data structures.

• Human-Readable Format:
  The Nuvira file format is designed to be easily readable by humans, with clear definitions and a structured, organized layout. This makes it simple to write, debug, and maintain, even for non-programmers or users unfamiliar with the technical details.

• Document Locking:
  The *LOCKED setting in the file rules allows you to lock file, preventing any further modifications. This feature ensures that once a file is finalized, it cannot be changed, maintaining data integrity over time.

• Support for Relationships:
  Nuvira supports complex relationships between different schemas. With the @relations section, you can define one-to-one, one-to-many, or many-to-many relationships between schemas, as well as actions to be taken on delete or update (e.g., cascading or restricting).

These features ensure that Nuvira is a highly flexible, robust, and efficient data format for managing structured, validated data, making it ideal for use in applications where data integrity, flexibility, and complex relationships are important.

Advantages of Nuvira Format