A codec can:

- decode inputs of type `I`,
- encode values to type `O`,
- be used as a [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates).

abstract is(input: unknown): input is A;
abstract encode(value: A): O;
abstract decode(input: I): Either;
}
```

As an example, here is a codec for integer encoded as a string:

```typescript
// Represents integer `number`, the first type parameter.
// If we encode a known number, it will turn into `string` (the second type parameter).
// If we want to receive a number, the codec can accept `string` as input to parse (the third type parameter).
// To decode `unknown` input do something like `string.pipe(numberAsString)`.
class IntAsStringCodec extends Codec {
constructor() {
super(`IntAsString`);
}

// Similar to `instanceof`.
is(input: unknown): input is number {
return typeof input === "number";
}

decode(input: string, context: Context): Validation {
const supposedlyInt = parseInt(input, 10);
// If an integer
if (supposedlyInt.toString() === input) {
// Return value
// Beware: do not return plain value, wrap it in `context.success`
return context.success(supposedlyInt);
} else {
// If anything is wrong, signal failure by returning `context.failure`.
// Whatever happens, **do not throw an error**.
return context.failure(`Not an integer`);
}
}

// Encode known value to string output.
encode(value: number): string {
return value.toString();
}
}

const intAsString = new IntAsStringCodec();
```

In most cases though, creating codecs this way is an overkill.
Codec combinators [provided by the library](#implemented-types) are enough for 90% of use cases.

The `Either` type represents a value of one of two possible types (a disjoint union):

- `Left` meaning _success_,
- `Right` meaning _failure_.

```typescript
type Either =
| {
readonly _tag: "Left";
readonly left: TError;
}
| {
readonly _tag: "Right";
readonly right: TValue;
};
```

You could check a result of validation using `isValid` or `isError` helpers:

```typescript
import { string, refinement, validate, isError } from "codeco";

const longString = refinement(string, (s) => s.length >= 100);
const validation = validate(longString, "short input");
if (isError(validation)) {
console.log("Validation errorr", validation.left);
}
const valid = validation.right; // Here goes proper long string
```

## Implemented types

## Linear parsing

In addition to structural encoding/decoding, we provide linear _parsing_ functions in form of Parser Combinators
available from 'codeco/linear':

```typescript
import * as P from "codeco/linear";
import { getOrThrow } from "codeco";

const line = P.seq(P.literal("My name is "), P.match(/\w+/));
const name = P.map(line, (parsed) => parsed[1]); // `map` combinator
const input = new P.StringTape("My name is Marvin"); // Prepare input for consumption
const decodedName = getOrThrow(P.parseAll(input)); // Would throw if input does not conform to expected format
```

Provided combinators: