[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [Type](https://evolu.dev/docs/api-reference/common/Type) › TupleType Defined in: [packages/common/src/Type.ts:8042](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L8042) The fixed-length heterogeneous [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) returned by [tuple](https://evolu.dev/docs/api-reference/common/Type/functions/tuple). ## Extends - [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Tuple"`, `TupleShape`\<`Elements`, `"Input"`\>, `TupleShape`\<`Elements`, `"Output"`\>, \[`TupleParents`\<`Elements`\>\] _extends_ \[`null`\] ? [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TupleError)\<`Elements`\[`number`\]\[`"Error"`\]\> : [`TupleElementsError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TupleElementsError)\<`TupleFromErrors`\<`Elements`\>\>, \[`TupleParents`\<`Elements`\>\] _extends_ \[`null`\] ? `null` : `RootTupleType`\<`RootTupleElements`\<`Elements`\>\>, [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TupleError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Elements`\[`number`\]\>\>, `never`, `TupleShape`\<`Elements`, `"CanonicalInput"`\>, `AllTypesUseIdentityEncoding`\<`Elements`\[`number`\]\>\> ## Properties ### \[concreteTypeSymbol\] ```ts readonly [concreteTypeSymbol]: true; ``` Defined in: [packages/common/src/Type.ts:455](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L455) #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[concreteTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type#concretetypesymbol) --- ### \[customFromSymbol\] ```ts readonly [customFromSymbol]: never; ``` Defined in: [packages/common/src/Type.ts:459](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L459) #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[customFromSymbol]`](/docs/api-reference/common/Type/interfaces/Type#customfromsymbol) --- ### \[errorsSymbol\] ```ts readonly [errorsSymbol]: TupleError; ``` Defined in: [packages/common/src/Type.ts:451](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L451) #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[errorsSymbol]`](/docs/api-reference/common/Type/interfaces/Type#errorssymbol) --- ### \[identityEncodingSymbol\] ```ts readonly [identityEncodingSymbol]: AllTypesUseIdentityEncoding; ``` Defined in: [packages/common/src/Type.ts:462](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L462) #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[identityEncodingSymbol]`](/docs/api-reference/common/Type/interfaces/Type#identityencodingsymbol) --- ### \[reflectedTypesSymbol\]? ```ts readonly optional [reflectedTypesSymbol]?: Elements[number]; ``` Defined in: [packages/common/src/Type.ts:8057](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L8057) --- ### ~standard ```ts readonly ~standard: Props, TupleShape>; ``` Defined in: [packages/common/src/Type.ts:402](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L402) Standard Schema V1 interoperability. Validation runs the complete `fromUnknown` pipeline synchronously and reports every structured failure as a localized message with a separate property path. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#standard) --- ### CanonicalInput ```ts CanonicalInput: TupleShape; ``` Defined in: [packages/common/src/Type.ts:387](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L387) The statically known subtype of [Input](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#input) returned by the complete `to` operation. Compared with Input, CanonicalInput can exclude invalid candidates and alternative representations that encoding cannot emit. It can remain wider than the values actually emitted when a refinement follows an arbitrary transformation. Structural Types derive it from the CanonicalInput of their contained Types. This is a type-only phantom property. Use it through `typeof Type.CanonicalInput`; it does not exist at runtime. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`CanonicalInput`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#canonicalinput) --- ### elements ```ts readonly elements: Elements; ``` Defined in: [packages/common/src/Type.ts:8058](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L8058) --- ### Error ```ts Error: [TupleParents] extends [null] ? TupleError : TupleElementsError>; ``` Defined in: [packages/common/src/Type.ts:381](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L381) The error introduced at this Type node. This is a type-only phantom property. Use it through `typeof Type.Error`; it does not exist at runtime. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#error) --- ### formatError ```ts readonly formatError: TypeErrorFormatter>>; ``` Defined in: [packages/common/src/Type.ts:508](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L508) Formats an error returned by `fromUnknown` or `from` as one human-readable message. Built-in Types use English; [localizeTypes](https://evolu.dev/docs/api-reference/common/Type/variables/localizeTypes) derives Types with localized formatters. Structural errors retain nested errors and their locations in the typed error value. This formatter does not encode paths or enumerate nested errors in its message. ### Example ```ts const result = String.fromUnknown(42); expectErr(result, { type: "TypeOf", expected: "String", value: 42 }); expect(String.formatError(result.error)).toBe("A value 42 is not a string."); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`formatError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#formaterror) --- ### from ```ts readonly from: [[TupleParents] extends [null] ? null : RootTupleType>] extends [P] ? FromOperation, [TupleParents] extends [null] ? TupleError : TupleElementsError>, P> : (value: Input, options?: ValidationOptions) => Result, never>; ``` Defined in: [packages/common/src/Type.ts:591](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L591) Runs the remaining Type pipeline from a typed boundary. `from` accepts this Type's `Output`. Its first `.parent` accepts the immediate parent Output, and each additional suffix moves the boundary one Type toward the root. The deepest suffix accepts the root Output. Every entry point asserts its selected boundary before running the remaining pipeline. Assertion failures throw because they indicate a developer error. The Error message identifies the expected boundary Type, and its cause preserves the structured validation error. Only failures introduced after that boundary are returned through `Result`. ### Example A form already guarantees every constraint on a title, while a new note input guarantees only trimmed text. The note's parent boundary validates only the constraints that the form does not guarantee: ```ts import { flatMapResult, NonEmptyTrimmedString100, object, TrimmedString, type MaxLengthError, type MinLengthError, type Result, } from "@evolu/common"; const Todo = object({ title: NonEmptyTrimmedString100, note: NonEmptyTrimmedString100, }); const saveTodo = (title: NonEmptyTrimmedString100, note: TrimmedString) => { // @ts-expect-error TrimmedString does not guarantee a non-empty value // with at most 100 characters. Todo.from({ title, note }); return flatMapResult(Todo.props.note.from.parent.parent(note), (note) => Todo.from({ title, note }), ); }; const title = NonEmptyTrimmedString100.orThrow("Buy milk"); const note = TrimmedString.orThrow("Remember oat milk"); const result = saveTodo(title, note); expectTypeOf(result).toEqualTypeOf< Result | MinLengthError<1>> >(); expectOk(result, { title, note }); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#from) --- ### fromUnknown ```ts readonly fromUnknown: (value: unknown, options?: ValidationOptions) => Result, TupleError>>; ``` Defined in: [packages/common/src/Type.ts:481](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L481) Decodes an unknown value through the complete Type pipeline. ### Example ```ts const value: unknown = 42; const result = PositiveInt.fromUnknown(value); expectOk(result, 42); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#fromunknown) --- ### Input ```ts Input: TupleShape; ``` Defined in: [packages/common/src/Type.ts:379](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L379) The complete typed decoding boundary accepted by `orThrow`, `orNull`, and the deepest available `from` operation. Input includes candidates that validation can reject and noncanonical representations that decoding can normalize. This is a type-only phantom property. Use it through `typeof Type.Input`; it does not exist at runtime. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#input) --- ### is ```ts readonly is: (value: unknown) => value is TupleShape; ``` Defined in: [packages/common/src/Type.ts:530](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L530) Checks whether an unknown value is a valid semantic `Output`. This is an exact Output-membership check, not a test of whether an encoded Input could be decoded. It can be used directly as a TypeScript type guard, including as an Array filter predicate. ### Example ```ts const values: ReadonlyArray = [42n, "42", null]; const integers = values.filter(Int64FromInt64String.is); expectTypeOf(integers).toEqualTypeOf>(); expect(Int64FromInt64String.is(42n)).toBe(true); expect(Int64FromInt64String.is("42")).toBe(false); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#is) --- ### name ```ts readonly name: "Tuple"; ``` Defined in: [packages/common/src/Type.ts:393](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L393) The name identifying this Type node. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#name-1) --- ### orNull ```ts readonly orNull: (value: Input) => TupleShape | null; ``` Defined in: [packages/common/src/Type.ts:686](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L686) Shorthand for calling [getOrNull](https://evolu.dev/docs/api-reference/common/Result/functions/getOrNull) with the result of the deepest `from` operation, which accepts this Type's `Input`. The typed `Input` boundary is asserted before the remaining pipeline runs. A boundary violation throws a developer error directly; `getOrNull` maps only a validation error returned after that boundary to `null`. `Type.orNull.parent(value)` does not exist. To return `null` after starting from a typed boundary, call `getOrNull` with the corresponding `from` operation. Use `orNull` when absence is the complete meaning of failure and the error is intentionally irrelevant. Use `fromUnknown` or a typed `from` operation when the caller needs to inspect, format, or otherwise handle the error. ### Example ```ts const NonEmptyString = minLength(1)(String); const value = NonEmptyString.orNull("Evolu"); // Equivalent because `from.parent` is this Type's deepest `from` operation: const sameValue = getOrNull(NonEmptyString.from.parent("Evolu")); expect(value).toBe("Evolu"); expect(sameValue).toBe(value); expect(NonEmptyString.orNull("")).toBeNull(); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#ornull) --- ### orThrow ```ts readonly orThrow: (value: Input, options?: ValidationOptions) => TupleShape; ``` Defined in: [packages/common/src/Type.ts:651](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L651) Shorthand for calling [getOrThrow](https://evolu.dev/docs/api-reference/common/Result/functions/getOrThrow) with the result of the deepest `from` operation, which accepts this Type's `Input`. The typed `Input` boundary is asserted before the remaining pipeline runs. A boundary violation throws a developer error directly; `getOrThrow` maps only a validation error returned after that boundary. `Type.orThrow.parent(value)` does not exist. To throw after starting from a typed boundary, call `getOrThrow` with the corresponding `from` operation. Use `orThrow` for startup and configuration, module constants, test fixtures, and internal invariants where failure must stop the current flow. Prefer `fromUnknown` or a typed `from` operation for ordinary application input whose validation failure can be reported or recovered from. ### Example ```ts const NonEmptyString = minLength(1)(String); const value = NonEmptyString.orThrow("Evolu"); // Equivalent because `from.parent` is this Type's deepest `from` operation: const sameValue = getOrThrow(NonEmptyString.from.parent("Evolu")); expect(value).toBe("Evolu"); expect(sameValue).toBe(value); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#orthrow) --- ### Output ```ts Output: TupleShape; ``` Defined in: [packages/common/src/Type.ts:380](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L380) The semantic value produced by decoding and accepted by bare `from` and `to`. This is a type-only phantom property. Use it through `typeof Type.Output`; it does not exist at runtime. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Output`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#output) --- ### parent ```ts readonly parent: [TupleParents] extends [null] ? null : RootTupleType>; ``` Defined in: [packages/common/src/Type.ts:465](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L465) The one preceding Type node, or `null` for a root Type. #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#parent-1) --- ### to ```ts readonly to: [[TupleParents] extends [null] ? null : RootTupleType>] extends [P] ? ToOperation, TupleShape, P> : (value: Output) => CanonicalInput; ``` Defined in: [packages/common/src/Type.ts:615](https://github.com/evoluhq/evolu/blob/b4566ffe09cda0a0a62de13ae1b30b57fd467e1f/packages/common/src/Type.ts#L615) Asserts and encodes an `Output` toward its canonical `Input` representation. `to` runs the complete encoding pipeline. Its first `.parent` stops at the immediate parent Output, and each additional suffix stops one Type closer to the root. Every entry point accepts this Type's `Output`. ### Example ```ts const value = Int64.orThrow(42n); expect(Int64FromInt64String.to(value)).toBe("42"); ``` #### Inherited from [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`to`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type#to)