LiteralAST node matching an exact primitive value (string, number, boolean, or bigint).
Details
Parsing succeeds only when the input is strictly equal (===) to the
stored literal. Numeric literals must be finite — Infinity, -Infinity,
and NaN are rejected at construction time.
Example (Creating a literal AST)
import { SchemaAST } from "effect"
const ast = new SchemaAST.Literal("active")
console.log(ast.literal) // "active"export class class Literalclass Literal {
_tag: 'Literal';
literal: LiteralValue;
getParser: () => SchemaParser.Parser;
matchPart: (s: string, _options: ParseOptions) => LiteralValue | undefined;
toCodecJson: () => AST;
toCodecStringTree: () => AST;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
AST node matching an exact primitive value (string, number, boolean, or
bigint).
Details
Parsing succeeds only when the input is strictly equal (===) to the
stored literal. Numeric literals must be finite — Infinity, -Infinity,
and NaN are rejected at construction time.
Example (Creating a literal AST)
import { SchemaAST } from "effect"
const ast = new SchemaAST.Literal("active")
console.log(ast.literal) // "active"
Literal extends class BaseRepresents the abstract base class for all
AST
node variants.
Details
Every AST node extends Base and inherits these fields:
annotations — user-supplied metadata (identifier, title, description,
arbitrary keys).checks — optional
Checks
for post-type-match validation.encoding — optional
Encoding
chain for type ↔ wire
transformations.context — optional
Context
for per-property metadata.
Subclasses add a _tag discriminant and variant-specific data.
Base {
readonly Literal._tag: "Literal"_tag = "Literal"
readonly Literal.literal: LiteralValueliteral: type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue
constructor(
literal: LiteralValueliteral: type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue,
annotations: | Schema.Annotations.Annotations
| undefined
import SchemaSchema.Annotations.interface Annotations.AnnotationsThis interface is used to define the annotations that can be attached to a
schema. You can extend this interface to define your own annotations.
Details
Note that both a missing key or undefined is used to indicate that the
annotation is not present.
This means that can remove any annotation by setting it to undefined.
Example (Defining your own annotations)
import { Schema } from "effect"
// Extend the Annotations interface with a custom `version` annotation
declare module "effect/Schema" {
namespace Annotations {
interface Annotations {
readonly version?:
| readonly [major: number, minor: number, patch: number]
| undefined
}
}
}
// The `version` annotation is now recognized by the TypeScript compiler
const schema = Schema.String.annotate({ version: [1, 2, 0] })
// const version: readonly [major: number, minor: number, patch: number] | undefined
const version = Schema.resolveAnnotations(schema)?.["version"]
if (version) {
// Access individual parts of the version
console.log(version[1])
// Output: 2
}
Annotations,
checks: Checkschecks?: type Checks = readonly [
Check<any>,
...Check<any>[]
]
Non-empty array of validation
Check
values attached to an AST node
via
Base.checks
.
Details
Checks are run after basic type matching succeeds. They represent
refinements like minLength, pattern, int, etc.
Checks,
encoding: Encodingencoding?: type Encoding = readonly [Link, ...Link[]]A non-empty chain of
Link
values representing the transformation
steps between a schema's decoded (type) form and its encoded (wire) form.
Details
Stored on
Base.encoding
. When undefined, the node has no
encoding transformation (type and encoded forms are identical).
Encoding,
context: Contextcontext?: class Contextclass Context {
isOptional: boolean;
isMutable: boolean;
defaultValue: Encoding | undefined;
annotations: Schema.Annotations.Key<unknown> | undefined;
}
Represents per-property metadata attached to AST nodes via
Base.context
.
Details
Tracks whether a property key is optional, mutable, has a constructor
default, or carries key-level annotations. Typically set by helpers like
optionalKey
and Schema.mutableKey.
isOptional — the property key may be absent from the input.isMutable — the property is readonly when false.defaultValue — an
Encoding
applied during construction to
supply missing values.annotations — key-level annotations (e.g. description of the key
itself).
Context
) {
super(annotations: | Schema.Annotations.Annotations
| undefined
checks: Checkschecks, encoding: Encodingencoding, context: Contextcontext)
if (typeof literal: LiteralValueliteral === "number" && !module globalThisglobalThis.var Number: NumberConstructorAn object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.
Number.NumberConstructor.isFinite(number: unknown): booleanReturns true if passed value is finite.
Unlike the global isFinite, Number.isFinite doesn't forcibly convert the parameter to a
number. Only finite values of the type number, result in true.
isFinite(literal: LiteralValueliteral)) {
throw new var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
function format(input: unknown, options?: {
readonly space?: number | string | undefined;
readonly ignoreToString?: boolean | undefined;
}): string
Converts any JavaScript value into a human-readable string.
When to use
Use when you need to format arbitrary JavaScript values for debugging,
logging, or error messages.
Details
- Output is not valid JSON; use
formatJson
when you need
parseable JSON.
- Handles
BigInt, Symbol, Set, Map, Date, RegExp, and class
instances that JSON.stringify cannot represent.
- Circular references are shown as
"[Circular]" instead of throwing.
- Primitives: stringified naturally (
null, undefined, 123, true).
Strings are JSON-quoted.
- Objects with a custom
toString (not Object.prototype.toString):
toString() is called unless ignoreToString is true.
- Errors with a
cause: formatted as "<message> (cause: <cause>)".
- Iterables (
Set, Map, etc.): formatted as
ClassName([...elements]).
- Class instances: wrapped as
ClassName({...}).
Redactable values are automatically redacted.- Arrays/objects with 0–1 entries are inline; larger ones are
pretty-printed when
space is set.
space — indentation unit (number of spaces, or a string like
"\t"). Defaults to 0 (compact).ignoreToString — skip calling toString(). Defaults to false.
Example (Formatting compact output)
import { Formatter } from "effect"
console.log(Formatter.format({ a: 1, b: [2, 3] }))
// {"a":1,"b":[2,3]}
Example (Pretty-printed output)
import { Formatter } from "effect"
console.log(Formatter.format({ a: 1, b: [2, 3] }, { space: 2 }))
// {
// "a": 1,
// "b": [
// 2,
// 3
// ]
// }
Example (Handling circular references)
import { Formatter } from "effect"
const obj: any = { name: "loop" }
obj.self = obj
console.log(Formatter.format(obj))
// {"name":"loop","self":[Circular]}
format(literal: LiteralValueliteral)}`)
}
this.Literal.literal: LiteralValueliteral = literal: LiteralValueliteral
}
/** @internal */
Literal.getParser(): SchemaParser.ParsergetParser() {
return function fromConst<T>(
ast: AST,
value: T
): SchemaParser.Parser
Literal.literal: LiteralValueliteral)
}
/** @internal */
Literal.matchPart(s: string, _options: ParseOptions): LiteralValue | undefinedmatchPart(s: strings: string, _options: ParseOptions(parameter) _options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue | undefined {
return s: strings === module globalThisglobalThis.var String: StringConstructor
;(value?: any) => string
Allows manipulation and formatting of text strings and determination and location of substrings within strings.
String(this.Literal.literal: LiteralValueliteral) ? this.Literal.literal: LiteralValueliteral : var undefinedundefined
}
/** @internal */
Literal.toCodecJson(): ASTtoCodecJson(): type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
Discriminated union of all AST node types.
Details
Every Schema has an .ast property of this type. Use the guard functions
(
isString
,
isObjects
, etc.) to narrow to a specific variant,
then access variant-specific fields.
- All variants share the
Base
fields:
annotations, checks,
encoding, context.
- Discriminate on the
_tag field (e.g. "String", "Objects", "Union").
AST {
return typeof this.Literal.literal: LiteralValueliteral === "bigint" ? function literalToString(
ast: Literal
): Literal
Literal.toCodecStringTree(): ASTtoCodecStringTree(): type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
Discriminated union of all AST node types.
Details
Every Schema has an .ast property of this type. Use the guard functions
(
isString
,
isObjects
, etc.) to narrow to a specific variant,
then access variant-specific fields.
- All variants share the
Base
fields:
annotations, checks,
encoding, context.
- Discriminate on the
_tag field (e.g. "String", "Objects", "Union").
AST {
return typeof this.Literal.literal: LiteralValueliteral === "string" ? this : function literalToString(
ast: Literal
): Literal
Literal.getExpected(): stringgetExpected(): string {
return typeof this.Literal.literal: LiteralValueliteral === "string" ? var JSON: JSONAn intrinsic object that provides functions to convert JavaScript values to and from the JavaScript Object Notation (JSON) format.
JSON.JSON.stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string (+1 overload)Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
stringify(this.Literal.literal: LiteralValueliteral) : module globalThisglobalThis.var String: StringConstructor
;(value?: any) => string
Allows manipulation and formatting of text strings and determination and location of substrings within strings.
String(this.Literal.literal: LiteralValueliteral)
}
}