docs(std): added missing inline documentations

Author: giveerr

packages/std/src/io/utils/read.ts

@@ -2,6 +2,10 @@ import { $fn, err } from '../../results'
 
 import { ioTags } from '../tag'
 
+/**
+ * The $read function reads a file from the specified path and
+ * returns its contents as a ArrayBuffer in AsyncResult.
+ */
 export const $read = $fn(async (path: string) => {
   const file = Bun.file(path)
   const exists = await file.exists()
@@ -13,6 +17,10 @@ export const $read = $fn(async (path: string) => {
   return await file.arrayBuffer()
 }, ioTags.get('read'))
 
+/**
+ * The $readJson function reads a file from the specified path and
+ * returns its contents as a object in AsyncResult.
+ */
 export const $readJson = $fn(async <T>(path: string) => {
   const file = Bun.file(path)
   const exists = await file.exists()

packages/std/src/io/utils/write.ts

@@ -3,6 +3,10 @@ import type { JsonValue } from '../../shared'
 
 import { ioTags } from '../tag'
 
+/**
+ * The $write function writes a file to the specified path and
+ * returns true in AsyncResult.
+ */
 export const $write = $fn(async (path: string, data: string | ArrayBuffer, create = true) => {
   const file = Bun.file(path)
   const exists = await file.exists()
@@ -16,6 +20,10 @@ export const $write = $fn(async (path: string, data: string | ArrayBuffer, creat
   return true
 }, ioTags.get('write'))
 
+/**
+ * The $writeJson function writes a object (as JSON) to the specified path and
+ * returns true in AsyncResult.
+ */
 export const $writeJson = $fn(async (path: string, data: JsonValue, create = true) => {
   const file = Bun.file(path)
   const exists = await file.exists()

packages/std/src/results/utils/async.ts

@@ -1,6 +1,9 @@
 import { Err } from './err'
 import { Ok } from './ok'
 
+/**
+ * This class converts a promise into ResultAsync
+ */
 export class ResultAsync<T, N extends Std.ErrorValues = never, C extends Std.ErrorValues[] = []>
   implements PromiseLike<Std.Result<T, N, C>>
 {
@@ -32,9 +35,15 @@ export class ResultAsync<T, N extends Std.ErrorValues = never, C extends Std.Err
   }
 }
 
+/**
+ * Shortcut for creating successful AsyncResult
+ */
 export const okAsync = <T>(value: T): ResultAsync<T, never, never> =>
   new ResultAsync(Promise.resolve(new Ok<T, never, never>(value)))
 
+/**
+ * Shortcut for creating failed AsyncResult
+ */
 export const errAsync = <N extends Std.ErrorValues>(
   err: N,
   message = ''

packages/std/src/results/utils/capsule.ts

@@ -4,6 +4,10 @@ import { ResultAsync } from './async'
 
 import { handleCatch, handleThen } from './internal/handlers'
 
+/**
+ * The capsule function is used to wrap a function for unknown errors
+ * This function doesn't return a Result or AsyncResult
+ */
 export const capsule = <A extends BlobType[], R>(
   fn: (...args: A) => R,
   ...additionalCauses: Std.ErrorValues[]

packages/std/src/results/utils/err.ts

@@ -2,6 +2,9 @@ import type { BlobType } from '../../shared'
 
 import type { Ok } from './ok'
 
+/**
+ * This class represents a failed result
+ */
 export class Err<
   T = never,
   const N extends Std.ErrorValues = never,
@@ -84,6 +87,9 @@ export class Err<
   }
 }
 
+/**
+ * Shortcut for creating failed result
+ */
 export function err<T = never, const N extends Std.ErrorValues = never>(
   name: N,
   message: string

packages/std/src/results/utils/fn.ts

@@ -6,6 +6,10 @@ import { handleCatch, handleThen } from './internal/handlers'
 const invalidUsage = resultTags.get('invalid-usage')
 const cause = resultTags.get('fn')
 
+/**
+ * The $fn function is used to wrap a function that returns a Result or ResultAsync
+ * and automatically handles the error cases.
+ */
 export const $fn = <A extends BlobType[], R, C extends Std.ErrorValues[] = []>(
   fn: (...args: A) => R,
   ...additionalCauses: C

packages/std/src/results/utils/from-throwable.ts

@@ -3,6 +3,9 @@ import type { BlobType } from '../../shared'
 import { ResultAsync } from './async'
 import { Ok } from './ok'
 
+/**
+ * Converts an async function that throws to a function that returns a ResultAsync
+ */
 export const fromAsyncThrowable = <A extends readonly BlobType[], T, R>(
   fn: (...args: A) => Promise<T>,
   errorFn: (err: unknown) => R

packages/std/src/results/utils/internal/handlers.ts

@@ -7,6 +7,9 @@ import { Ok, ok } from '../ok'
 
 const invalidUsage = resultTags.get('invalid-usage')
 
+/**
+ * This helper extracts the actual value from its first argument (even its nested ok's or okAsync)
+ */
 export const handleThen = (
   data: BlobType,
   ...additionalCauses: Std.ErrorValues[]
@@ -56,6 +59,9 @@ export const handleThen = (
   return ok(result)
 }
 
+/**
+ * This helper adds additional causes to an error
+ */
 export const handleCatch = (
   e: BlobType,
   ...additionalCauses: Std.ErrorValues[]
@@ -64,7 +70,7 @@ export const handleCatch = (
     return e.appendCause(...additionalCauses)
   }
 
-  return err(invalidUsage, 'incorrect $fn usage')
+  return err(invalidUsage, 'incorrect usage of handleCatch')
     .appendCause(...additionalCauses)
     .appendData(e)
 }

packages/std/src/results/utils/ok.ts

@@ -2,6 +2,9 @@ import type { BlobType } from '../../shared'
 
 import type { Err } from './err'
 
+/**
+ * This class represents a successful result
+ */
 export class Ok<T, const N extends Std.ErrorValues = never, const C extends Std.ErrorValues[] = []>
   implements Std.ResultType<T, N, C>
 {
@@ -33,4 +36,7 @@ export class Ok<T, const N extends Std.ErrorValues = never, const C extends Std.
   }
 }
 
+/**
+ * Shortcut for creating successful result
+ */
 export const ok = <T>(value: T) => new Ok(value)

packages/std/src/results/utils/tag.ts

@@ -2,11 +2,19 @@ import type { BlobType, LiteralUnion } from '../../shared'
 
 import { err } from './err'
 
+/**
+ * Tags Manager for result system. It's used to create a tag for a result.
+ * Use `Tags.create` to create a new instance. Use `Tags.add` to add a new tag.
+ * For better type inference, use with chaining `Tags.add(...).add(...)`.
+ */
 export class Tags<U extends [string, string], T extends string> {
   tags = new Map<string, string>()
 
   constructor(protected base: T) {}
 
+  /**
+   * Adds a new tag to the Tag Manager.
+   */
   add<K extends string, V extends string = never>(key: K, value?: V) {
     const tag = `${this.base}.${value ?? key}`
 
@@ -17,6 +25,10 @@ export class Tags<U extends [string, string], T extends string> {
     return this as Tags<U | [K, V], T>
   }
 
+  /**
+   * Gets a specific key (can be a tag or a value) from the Tag Manager.
+   * If the key is not found, an error is thrown.
+   */
   get<K extends LiteralUnion<U['0'], `?${string}`>>(key: K) {
     const found = this.tags.get(key)
 
@@ -31,6 +43,9 @@ export class Tags<U extends [string, string], T extends string> {
     return found as R extends never ? `${T}.${K}` : `${T}.${R}`
   }
 
+  /**
+   * Checks if the Tag Manager has a specific key (can be a tag or a value).
+   */
   has<const K extends string>(
     key: K
   ): K extends Std.ExtractErrors<Tags<U, T>> ? true : K extends U['0'] ? true : false {

packages/std/src/results/utils/try.ts

@@ -6,6 +6,12 @@ import { handleCatch, handleThen } from './internal/handlers'
 const invalidUsage = resultTags.get('invalid-usage')
 const cause = resultTags.get('try')
 
+/**
+ * Executes the given generator function and returns the result.
+ *
+ * If the function throws an error, the error is wrapped in a result and returned.
+ * If the function returns a result, the result is returned.
+ */
 export function $try<R, R2, C extends Std.ErrorValues[] = []>(
   body: () => Generator<R, R2>,
   ...additionalCauses: C

packages/std/src/shared/utils/timing.ts

@@ -1,3 +1,6 @@
+/**
+ * Waits for a specified amount of time and returns a default value passed as a parameter
+ */
 export const wait = async <T = true>(ms: number, defaultValue?: T): Promise<T> => {
   return new Promise(resolve => {
     setTimeout(() => {