@wrikka/create-docs 0.1.0

package/src/shared/types/result.ts

@@ -0,0 +1,81 @@
+/**
+ * Result<T, E> — A pure algebraic data type for synchronous operations
+ * that can fail with a typed error.
+ *
+ * Use this over throwing exceptions at the boundaries (domain, application).
+ * Domain must never throw — only return Result.
+ *
+ * @example
+ *   const divide = (a: number, b: number): Result<number, string> =>
+ *     b === 0 ? err('Division by zero') : ok(a / b);
+ */
+export type Result<T, E> =
+	| { readonly ok: true; readonly value: T }
+	| { readonly ok: false; readonly error: E };
+
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });
+
+export const isOk = <T, E>(r: Result<T, E>): r is { ok: true; value: T } =>
+	r.ok;
+
+export const isErr = <T, E>(r: Result<T, E>): r is { ok: false; error: E } =>
+	!r.ok;
+
+export const map = <T, U, E>(
+	r: Result<T, E>,
+	fn: (value: T) => U,
+): Result<U, E> => (r.ok ? ok(fn(r.value)) : r);
+
+export const mapErr = <T, E, F>(
+	r: Result<T, E>,
+	fn: (error: E) => F,
+): Result<T, F> => (r.ok ? r : err(fn(r.error)));
+
+export const flatMap = <T, U, E>(
+	r: Result<T, E>,
+	fn: (value: T) => Result<U, E>,
+): Result<U, E> => (r.ok ? fn(r.value) : r);
+
+export const unwrap = <T, E>(r: Result<T, E>): T => {
+	if (r.ok) return r.value;
+	throw new Error(`unwrap on Err: ${String(r.error)}`);
+};
+
+export const unwrapOr = <T, E>(r: Result<T, E>, fallback: T): T =>
+	r.ok ? r.value : fallback;
+
+export const fromThrowable = <T, E = Error>(
+	fn: () => T,
+	onError: (e: unknown) => E,
+): Result<T, E> => {
+	try {
+		return ok(fn());
+	} catch (e) {
+		return err(onError(e));
+	}
+};
+
+export const all = <T, E>(
+	results: readonly Result<T, E>[],
+): Result<readonly T[], E> => {
+	const values: T[] = [];
+	for (const r of results) {
+		if (!r.ok) return r;
+		values.push(r.value);
+	}
+	return ok(values);
+};
+
+export const partition = <T, E>(
+	results: readonly Result<T, E>[],
+): { ok: readonly T[]; err: readonly E[] } => {
+	const okValues: T[] = [];
+	const errValues: E[] = [];
+	for (const r of results) {
+		if (r.ok) okValues.push(r.value);
+		else errValues.push(r.error);
+	}
+	return { ok: okValues, err: errValues };
+};

package/src/shared/utils/array.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure array utility functions. No mutation, no side effects.
+ * All functions are total — they handle empty arrays gracefully.
+ */
+
+export const isEmpty = <T>(arr: readonly T[]): boolean => arr.length === 0;
+
+export const first = <T>(arr: readonly T[]): T | undefined => arr[0];
+
+export const last = <T>(arr: readonly T[]): T | undefined =>
+	arr[arr.length - 1];
+
+export const unique = <T>(arr: readonly T[]): T[] => Array.from(new Set(arr));
+
+export const uniqueBy = <T, K>(
+	arr: readonly T[],
+	keyFn: (item: T) => K,
+): T[] => {
+	const seen = new Set<K>();
+	const out: T[] = [];
+	for (const item of arr) {
+		const k = keyFn(item);
+		if (!seen.has(k)) {
+			seen.add(k);
+			out.push(item);
+		}
+	}
+	return out;
+};
+
+export const groupBy = <T, K extends string>(
+	arr: readonly T[],
+	keyFn: (item: T) => K,
+): Record<K, T[]> => {
+	const out = {} as Record<K, T[]>;
+	for (const item of arr) {
+		const k = keyFn(item);
+		if (!out[k]) out[k] = [];
+		out[k].push(item);
+	}
+	return out;
+};
+
+export const sortBy = <T>(arr: readonly T[], keyFn: (item: T) => number): T[] =>
+	[...arr].sort((a, b) => keyFn(a) - keyFn(b));
+
+export const sortByString = <T>(
+	arr: readonly T[],
+	keyFn: (item: T) => string,
+): T[] => [...arr].sort((a, b) => keyFn(a).localeCompare(keyFn(b)));
+
+export const partitionBy = <T>(
+	arr: readonly T[],
+	pred: (item: T) => boolean,
+): { yes: T[]; no: T[] } => {
+	const yes: T[] = [];
+	const no: T[] = [];
+	for (const item of arr) {
+		if (pred(item)) yes.push(item);
+		else no.push(item);
+	}
+	return { yes, no };
+};
+
+export const filterMap = <T, U>(
+	arr: readonly T[],
+	fn: (item: T) => U | undefined,
+): U[] => {
+	const out: U[] = [];
+	for (const item of arr) {
+		const v = fn(item);
+		if (v !== undefined) out.push(v);
+	}
+	return out;
+};
+
+export const chunk = <T>(arr: readonly T[], size: number): T[][] => {
+	if (size <= 0) throw new Error("chunk: size must be > 0");
+	const out: T[][] = [];
+	for (let i = 0; i < arr.length; i += size) {
+		out.push(arr.slice(i, i + size));
+	}
+	return out;
+};
+
+export const flatten = <T>(arr: readonly (readonly T[])[]): T[] => arr.flat();
+
+export const zip = <A, B>(a: readonly A[], b: readonly B[]): Array<[A, B]> => {
+	const len = Math.min(a.length, b.length);
+	const out: Array<[A, B]> = [];
+	for (let i = 0; i < len; i++) {
+		const av = a[i];
+		const bv = b[i];
+		if (av !== undefined && bv !== undefined) out.push([av, bv]);
+	}
+	return out;
+};

package/src/shared/utils/index.ts

@@ -0,0 +1,46 @@
+export {
+	chunk,
+	filterMap,
+	first,
+	flatten,
+	groupBy,
+	isEmpty,
+	last,
+	partitionBy,
+	sortBy,
+	sortByString,
+	unique,
+	uniqueBy,
+	zip,
+} from "./array";
+export {
+	isArray,
+	isBoolean,
+	isNonEmptyArray,
+	isNonEmptyString,
+	isNumber,
+	isPlainObject,
+	isString,
+	keys,
+	omit,
+	pick,
+} from "./object";
+export {
+	capitalize,
+	endsWith,
+	isBlank,
+	isEmptyString,
+	removeExtension,
+	slugify,
+	splitLines,
+	startsWith,
+	stripLeadingSlash,
+	stripPrefix,
+	stripQuotes,
+	stripSuffix,
+	stripTrailingSlash,
+	titleCase,
+	toPosixPath,
+	trim,
+	truncate,
+} from "./string";

package/src/shared/utils/object.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure object utility functions. No mutation of inputs.
+ */
+
+export const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+	typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const isString = (v: unknown): v is string => typeof v === "string";
+
+export const isNumber = (v: unknown): v is number =>
+	typeof v === "number" && !Number.isNaN(v);
+
+export const isBoolean = (v: unknown): v is boolean => typeof v === "boolean";
+
+export const isArray = Array.isArray as <T>(v: unknown) => v is T[];
+
+export const isNonEmptyString = (v: unknown): v is string =>
+	isString(v) && v.length > 0;
+
+export const isNonEmptyArray = <T>(
+	v: readonly T[],
+): v is readonly [T, ...T[]] => v.length > 0;
+
+export const keys = <T extends object>(o: T): readonly (keyof T)[] =>
+	Object.keys(o) as (keyof T)[];
+
+export const pick = <T extends object, K extends keyof T>(
+	o: T,
+	ks: readonly K[],
+): Pick<T, K> => {
+	const out = {} as Pick<T, K>;
+	for (const k of ks) {
+		if (k in o) out[k] = o[k];
+	}
+	return out;
+};
+
+export const omit = <T extends object, K extends keyof T>(
+	o: T,
+	ks: readonly K[],
+): Omit<T, K> => {
+	const out = { ...o };
+	for (const k of ks) {
+		delete out[k];
+	}
+	return out;
+};

package/src/shared/utils/string.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure string utility functions.
+ */
+
+export const trim = (s: string): string => s.trim();
+
+export const isBlank = (s: string): boolean => s.trim().length === 0;
+
+export const isEmptyString = (s: string): boolean => s.length === 0;
+
+export const startsWith = (s: string, prefix: string): boolean =>
+	s.startsWith(prefix);
+
+export const endsWith = (s: string, suffix: string): boolean =>
+	s.endsWith(suffix);
+
+export const stripPrefix = (s: string, prefix: string): string =>
+	s.startsWith(prefix) ? s.slice(prefix.length) : s;
+
+export const stripSuffix = (s: string, suffix: string): string =>
+	s.endsWith(suffix) ? s.slice(0, -suffix.length) : s;
+
+export const removeExtension = (s: string, ext: string): string =>
+	stripSuffix(s, ext);
+
+/** Replace all forward slashes and backslashes with the platform-agnostic `/`. */
+export const toPosixPath = (s: string): string => s.replace(/\\/g, "/");
+
+/** Strip a leading slash. */
+export const stripLeadingSlash = (s: string): string =>
+	s.startsWith("/") ? s.slice(1) : s;
+
+/** Strip a trailing slash. */
+export const stripTrailingSlash = (s: string): string =>
+	s.endsWith("/") && s.length > 1 ? s.slice(0, -1) : s;
+
+/** Capitalize the first character. */
+export const capitalize = (s: string): string =>
+	s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+
+/** Title-case each dash/underscore separated word. */
+export const titleCase = (s: string): string =>
+	s
+		.split(/[-_\s]+/)
+		.filter((w) => w.length > 0)
+		.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+		.join(" ");
+
+export const slugify = (s: string): string =>
+	s
+		.toLowerCase()
+		.trim()
+		.replace(/[^a-z0-9\s-]/g, "")
+		.replace(/\s+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+
+export const truncate = (s: string, max: number, suffix = "..."): string =>
+	s.length <= max
+		? s
+		: `${s.slice(0, Math.max(0, max - suffix.length))}${suffix}`;
+
+export const splitLines = (s: string): string[] => s.split(/\r?\n/);
+
+export const stripQuotes = (s: string): string => {
+	const t = s.trim();
+	if (
+		(t.startsWith('"') && t.endsWith('"')) ||
+		(t.startsWith("'") && t.endsWith("'"))
+	) {
+		return t.slice(1, -1);
+	}
+	return t;
+};

package/src/toc-generator/index.ts

@@ -0,0 +1 @@
+export * from "../modules/toc-generator";

package/src/types/js-yaml.d.ts

@@ -0,0 +1,42 @@
+declare module "js-yaml" {
+	export interface LoadOptions {
+		filename?: string;
+		json?: boolean;
+		onWarning?: (error: unknown) => void;
+		schema?: Schema;
+	}
+
+	export interface DumpOptions {
+		indent?: number;
+		lineWidth?: number;
+		noRefs?: boolean;
+		schema?: Schema;
+	}
+
+	export interface Schema {}
+
+	export const DEFAULT_SCHEMA: Schema;
+	export const JSON_SCHEMA: Schema;
+	export const YAMLException: new (
+		message?: string,
+		mark?: { line: number; column: number },
+	) => Error & { mark?: { line: number; column: number } };
+
+	export function load(input: string, options?: LoadOptions): unknown;
+	export function loadAll(input: string, options?: LoadOptions): unknown[];
+	export function dump(input: unknown, options?: DumpOptions): string;
+	export function safeLoad(input: string, options?: LoadOptions): unknown;
+	export function safeLoadAll(input: string, options?: LoadOptions): unknown[];
+	export function safeDump(input: unknown, options?: DumpOptions): string;
+
+	const yaml: {
+		load: typeof load;
+		dump: typeof dump;
+		safeLoad: typeof safeLoad;
+		safeDump: typeof safeDump;
+		DEFAULT_SCHEMA: Schema;
+		JSON_SCHEMA: Schema;
+		YAMLException: typeof YAMLException;
+	};
+	export default yaml;
+}