Gubu: Object Shape Validation Utility

Common errors

• Gubu: [path]: is required

  cause A field defined with a JavaScript type constructor (e.g., `Number`, `Boolean`) was missing from the input object being validated.
  fix Ensure all required fields are present in the object provided for validation, or modify the schema to make the field optional with a default if applicable.

• Gubu: [path]: is not a [type]

  cause A field in the input object did not match the expected primitive type (e.g., a string was provided for a `Number` field) as defined in the schema.
  fix Correct the type of the value in the input object to align with the schema's expectation for that specific field.

• TypeError: Gubu is not a function

  cause Incorrect import or require syntax, most commonly attempting to use `import Gubu from 'gubu'` when `Gubu` is a named export, or incorrectly accessing the export in CommonJS (`require('gubu').Gubu`).
  fix For ESM, use `import { Gubu } from 'gubu'`. For CommonJS, use `const { Gubu } = require('gubu')`.

Warnings

• gotcha Gubu deliberately mutates the input object passed to the validation function. This can lead to unexpected side effects if the original object is intended to remain immutable elsewhere in the application.
  Fix: If immutability is required, clone the input object before passing it to Gubu (e.g., using `structuredClone` or `lodash.cloneDeep`).
• gotcha The method for defining optional fields with defaults versus strictly required fields differs significantly. Literal values (e.g., `port: 8080`) define optional fields with that literal as the default, while JavaScript type constructors (e.g., `timeout: Number`, `secure: Boolean`) define required fields without defaults.
  Fix: Carefully review the schema definition: use literal values for optional fields with defaults, and type constructors (Number, String, Boolean, Object, Array) for strictly required fields. If a required field needs a default, consult Gubu's documentation for specific modifiers (e.g., `.Default()` if available).
• breaking Upgrading to a new major version (e.g., 9.x.x) may introduce breaking changes to the API, schema definition syntax, or validation behavior. Always consult the official release notes before upgrading major versions.
  Fix: Thoroughly read the release notes for the new major version on the package's GitHub repository or npm page. Test your application comprehensively after upgrading.

Install

• npm install gubu npm
• yarn add gubu yarn
• pnpm add gubu pnpm

Imports

• Gubu
  wrong:

  import Gubu from 'gubu'

  correct:

  import { Gubu } from 'gubu'

  Gubu is a named export. Attempting a default import will result in an error.
• Gubu
  wrong:

  const Gubu = require('gubu').Gubu

  correct:

  const { Gubu } = require('gubu')

  For CommonJS, use object destructuring to get the Gubu constructor from the module exports. The package supports both ESM and CJS.
• GubuSchema

  import type { GubuSchema } from 'gubu'

  While Gubu ships with TypeScript types, specific type names like 'GubuSchema' are inferred common patterns; refer to the package's type declarations for exact type exports. Use 'import type' for type-only imports to ensure they are stripped from the JavaScript output.

Quickstart

This quickstart demonstrates defining a Gubu schema with optional fields (having defaults), required fields (using type constructors like `Boolean`), array validation, and deep object merging. It also showcases how Gubu mutates the input object and catches various validation errors.

import { Gubu } from 'gubu' // Using ESM syntax for modern projects

const optionsShape = Gubu({
  server: {
    port: 8080,        // Default 8080, optional
    host: 'localhost', // Default 'localhost', optional
    secure: Boolean    // Required boolean, no default
  },
  client: {
    timeout: Number,   // Required number, no default
    debug: Boolean,    // Required boolean, no default
    headers: [String], // Array of strings, optional, empty array default if not provided
    retries: 3         // Default 3, optional
  },
  plugins: [            // Array of objects, optional, empty array default
    { 
      name: String,     // Required string
      enabled: Boolean  // Required boolean
    }
  ]
})

console.log('--- Scenario 1: Empty input, check defaults and required fields ---')
let config1 = {}
try {
  optionsShape(config1) // Mutates config1
  console.log('Validated Config 1:', JSON.stringify(config1, null, 2))
} catch (e: any) {
  console.error('Validation Error 1:', e.message)
}

console.log('\n--- Scenario 2: Partial input, check deep merging and specific values ---')
let config2 = {
  server: {
    port: 9000,
    secure: true
  },
  client: {
    timeout: 5000,
    debug: false,
    headers: ['X-Custom-Header-A']
  }
}
try {
  optionsShape(config2) // Mutates config2
  console.log('Validated Config 2:', JSON.stringify(config2, null, 2))
} catch (e: any) {
  console.error('Validation Error 2:', e.message)
}

console.log('\n--- Scenario 3: Invalid input type for a field ---')
let config3 = {
  server: {
    port: 'not-a-number', // Invalid type
    secure: true
  },
  client: {
    timeout: 1000,
    debug: true,
    headers: []
  }
}
try {
  optionsShape(config3)
  console.log('Validated Config 3:', JSON.stringify(config3, null, 2))
} catch (e: any) {
  console.error('Validation Error 3:', e.message)
}

console.log('\n--- Scenario 4: Missing a required field ---')
let config4 = {
  server: {
    port: 8080,
    // secure is missing
  },
  client: {
    timeout: 1000,
    debug: true,
    headers: []
  }
}
try {
  optionsShape(config4)
  console.log('Validated Config 4:', JSON.stringify(config4, null, 2))
} catch (e: any) {
  console.error('Validation Error 4:', e.message)
}