API reference / @evolu/common / Type / object

Function: object()

Defined in: packages/common/src/Type.ts:2597

Object Type.

This validates that:

The value is a plain object (checked with isPlainObject).
The object has no extra properties beyond the specified keys unless an index signature is provided.
Each property's value matches the specified Type.

When an index signature is included, the object can have additional keys that conform to the specified key and value Types.

The resulting ObjectType includes props for reflection, which defines the expected structure, and optionally an record for flexible key/value pairs.

https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures

Examples

Basic Object Validation

const User = object({
  name: NonEmptyTrimmedString,
  age: PositiveNumber,
});
type User = typeof User.Type;

const result = User.from({ name: "John", age: 30 }); // ok({ name: "John", age: 30 })
const error = User.from({ name: "John", age: -5 }); // err

Optional Properties

In this example the age property is marked as optional using optional.

const User = object({
  name: NonEmptyString, // Required
  age: optional(PositiveNumber), // Optional
});
type User = typeof User.Type;

Allowing Additional Properties

const UserWithAnyExtraProperties = object(
  {
    name: NonEmptyString,
    age: PositiveNumber,
  },
  record(String, Unknown),
);

expect(UserWithAnyExtraProperties.from({ name: "a", age: 1, foo: 1 })).toEqual({
  ok: true,
  value: { age: 1, foo: 1, name: "a" },
});

Combining Fixed and Flexible Properties

const NumberDictionary = object({ length: Number }, record(String, Number));

const validInput = {
  length: 5,
  extraKey1: 10,
  extraKey2: 15,
};

const fromResult = NumberDictionary.from(validInput);
expect(fromResult).toEqual(ok(validInput));

const invalidInput = {
  length: 5,
  extraKey1: "not a number",
  extraKey2: 15,
};

const invalidFromResult = NumberDictionary.fromUnknown(invalidInput);
expect(invalidFromResult).toEqual(
  err({
    type: "Object",
    value: invalidInput,
    reason: {
      kind: "IndexValue",
      key: "extraKey1",
      error: { type: "Number", value: "not a number" },
    },
  }),
);

Type Parameters

Type Parameter
`Props` extends `Record`<`string`, `AnyType`>

Parameters

Parameter	Type
`props`	`Props`

Returns

ObjectType<Props>

Defined in: packages/common/src/Type.ts:2601