Option

deno.jsonc

@@ -1,6 +1,7 @@
 {
 	"name": "@suddenly-giovanni/std",
 	"version": "0.0.4",
+	"lock": true,
 	"exports": {
 		"./predicate": "./src/predicate/mod.ts",
 		"./option": "./src/option/mod.ts"

src/internal/function.ts

@@ -1,5 +1,32 @@
 // deno-lint-ignore-file ban-types
 
+/**
+ * A lazy computation that can be used to defer the evaluation of an expression.
+ *
+ * @example
+ * To defer the evaluation of an expression:
+ * ```ts
+ * import { type Lazy } from './function.ts'
+ * declare function fib(n: number): number
+ *
+ * const lazy: Lazy<number> = () => fib(100) // fib is not called yet, hence the computation is deferred
+ * ```
+ *
+ * @example
+ * As a parameter type in a function:
+ * ```ts
+ * import { type Lazy } from './function.ts'
+ * function defer<A>(f: Lazy<A>): A {
+ * 	return f()
+ * }
+ * const value = defer(() => 1) // 1
+ *  ```
+ */
+export interface Lazy<A> {
+	// biome-ignore lint/style/useShorthandFunctionType: we want the opaque type here
+	(): A
+}
+
 /**
  * Pipes the value of an expression into a pipeline of functions.
  *

src/internal/types.test.ts

@@ -0,0 +1,23 @@
+import { expectTypeOf } from 'npm:expect-type@0.19.0'
+import { describe, test } from 'jsr:@std/testing/bdd'
+import type { Types } from './types.ts'
+
+describe('Types', () => {
+	test('Tag', () => {
+		expectTypeOf<Types.Tags<string | { _tag: 'a' } | { _tag: 'b' }> & unknown>().toEqualTypeOf<
+			'a' | 'b'
+		>()
+	})
+
+	test('Equal', () => {
+		expectTypeOf<Types.Equals<{ a: number }, { a: number }>>().toEqualTypeOf<true>()
+		expectTypeOf<Types.Equals<{ a: number }, { b: number }>>().toEqualTypeOf<false>()
+	})
+
+	test('Simplify', () => {
+		expectTypeOf<Types.Simplify<object & { a: number } & { b: number }>>().toEqualTypeOf<{
+			a: number
+			b: number
+		}>()
+	})
+})

src/internal/types.ts

@@ -0,0 +1,66 @@
+/**
+ * This namespace provides utility types for type manipulation.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from './types.ts'
+ *
+ * type Test1 = Types.Tags<string | { _tag: 'a' } | { _tag: 'b'} >
+ * //      ^? "a" | "b"
+ *
+ * type Test2 = Types.Equals<{ a: number }, { a: number }>
+ * //       ^? true
+ *
+ * type Test3 = Types.Simplify<{ a: number } & { b: number }>
+ * //   ^? { a: number; b: number; }
+ *
+ * ```
+ */
+export declare namespace Types {
+	/**
+	 * Returns the tags in a type.
+	 *
+	 *  @example
+	 * ```ts
+	 * import type { Types } from './types.ts'
+	 *
+	 * type Res = Types.Tags<string | { _tag: 'a' } | { _tag: 'b'} > // "a" | "b"
+	 * ```
+	 *
+	 * @category types
+	 */
+	export type Tags<E> = E extends { _tag: string } ? E['_tag'] : never
+
+	/**
+	 * Determines if two types are equal.
+	 *
+	 * @example
+	 * ```ts
+	 * import type { Types } from './types.ts'
+	 *
+	 * type Res1 = Types.Equals<{ a: number }, { a: number }> // true
+	 * type Res2 = Types.Equals<{ a: number }, { b: number }> // false
+	 * ```
+	 *
+	 * @category models
+	 */
+	export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
+		? true
+		: false
+
+	/**
+	 * Simplifies the type signature of a type.
+	 *
+	 * @example
+	 * ```ts
+	 * import type { Types } from './types.ts'
+	 *
+	 * type Res = Types.Simplify<{ a: number } & { b: number }> // { a: number; b: number; }
+	 * ```
+	 * @category types
+	 */
+	export type Simplify<A> = {
+		[K in keyof A]: A[K]
+	} extends infer B ? B
+		: never
+}

src/option/mod.ts

@@ -1 +1,44 @@
+/**
+ * # Option Module
+ * The Option Module is inspired by the Scala 3 Option type. This module primarily solves one of the common problems in programming - avoiding null and undefined values.
+ *
+ * The Option type is a container that encapsulates an optional value, i.e., it stores some value or none. It's a safer alternative to using null or undefined. By using Option, you can avoid null reference errors. The main advantage of using an `Option` type is that you're explicitly dealing with something that may or may not be there.
+ *
+ * ## How it works
+ * This module exports a base abstract class `Option` and two concrete subclasses `Some` and `None`. An `Option` object encapsulates a value that may or may not be present. A `Some` object represents an `Option` that contains a value, and `None` represents an `Option` that has no value.
+ *
+ * ## How to use it
+ * When you have a value that you want to lift into a boxed `Option`, you create an object of type `Some`, as follows:
+ *
+ * ```ts
+ * import { Option } from './option.ts'
+ *
+ * const value: Option.Type<string> = Option.Some("Hello, world!");
+ * ```
+ *
+ * If there isn't a value to lift, you create a `None` object, as follows:
+ *
+ * ```ts
+ * import { Option } from './option.ts'
+ *
+ * const none: Option.Type<never> = Option.None();
+ * ```
+ *
+ * To check the contents of an `Option`, use the `isSome` and `isNone` methods and extract the value when it is `Some`:
+ *
+ * ```ts
+ * import { Option } from './option.ts'
+ *
+ * const none: Option.Type<never> = Option.None();
+ *
+ * if (none.isSome()) {
+ *   console.log(none.get()); // this will throw an error !!!
+ * } else {
+ *   console.log("Value is None");
+ * }
+ * ```
+ *
+ * @module
+ */
+
 export { Option } from './option.ts'