# Option API Surface

These are ALL available methods for Option. Do not use any method not listed here.

## Types

```typescript
type Option<T> = Some<T> | None
type OptionPromise<T> = Promise<Option<T>>
type SomePromise<T> = Promise<Some<T>>
type NonePromise = Promise<None>
type OptionPartitionResult<T> = { values: T[]; noneCount: number }
type OptionFromType<T> = /* conditional: Some<NonNullable<T>> if T excludes null|undefined, else Option<NonNullable<T>> */
```

## Factory Functions

```typescript
function some<T>(value: T): Some<T>
function none(): None  // returns frozen singleton
```

## Some<T> Instance Methods

```typescript
class Some<T> {
  readonly value: T

  isSome(): this is Some<T>
  isNone(): this is never

  map<U>(fn: (value: T) => U): Some<U>

  flatMap<R extends Option<any>>(fn: (value: T) => R): R

  match<U>(onSome: (value: T) => U, onNone: () => U): U

  // Overload 1: type-narrowing predicate
  filter<U extends T>(predicate: (value: T) => value is U): Option<U>
  // Overload 2: boolean predicate
  filter(predicate: (value: T) => boolean): Option<T>

  toNullable(): T
  toUndefined(): T
  toString(): string
}
```

## None Instance Methods

```typescript
class None {
  // None has no .value property

  isSome(): this is never
  isNone(): this is None

  map<U>(): None

  flatMap(): this

  match<U>(onSome: (value: never) => U, onNone: () => U): U

  filter(): None

  toNullable(): null
  toUndefined(): undefined
  toString(): string
}
```

## NOT available on Option (Result/Query only)

- `mapErr()` — does not exist
- `flatMapErr()` — does not exist

## Option Namespace (Static Methods)

```typescript
Option.from<T>(value: T): OptionFromType<T>
Option.from<T>(fn: () => T): OptionFromType<T>
Option.isOption<T>(value: unknown): value is Option<T>
Option.all<T>(options: Some<T>[]): Some<T[]>
Option.all<T>(options: Option<T>[]): Option<T[]>
Option.partition<T>(options: Option<T>[]): OptionPartitionResult<T>
Option.compact<T>(options: Option<T>[]): T[]
Option.some<T>(options: Option<T>[]): boolean
Option.every<T>(options: Option<T>[]): boolean
```

## OptionPromise Namespace (Async Methods)

```typescript
OptionPromise.from<T>(fn: () => Promise<T>): Promise<OptionFromType<T>>
OptionPromise.all<T>(promises: Promise<Some<T>>[]): Promise<Some<T[]>>
OptionPromise.all<T>(promises: Promise<Option<T>>[]): Promise<Option<T[]>>
OptionPromise.partition<T>(promises: Promise<Option<T>>[]): Promise<OptionPartitionResult<T>>
OptionPromise.compact<T>(promises: Promise<Option<T>>[]): Promise<T[]>
OptionPromise.some<T>(promises: Promise<Option<T>>[]): Promise<boolean>
OptionPromise.every<T>(promises: Promise<Option<T>>[]): Promise<boolean>
```