@heyramzi/utils 0.0.0-stage → 1.13.0

package/src/package-imports.test.mjs

@@ -0,0 +1,22 @@
+import { expect, test } from "vite-plus/test";
+import { packageImportsOverKitAlias } from "#src/vite.js";
+
+test("package imports survive Kit aliases without removing unrelated aliases", () => {
+  const aliases = [
+    { find: /^#src\/(.+)$/, replacement: "/app/src/$1" },
+    { find: /^#scripts\/(.+)$/, replacement: "/app/scripts/$1" },
+    { find: /^\$lib\/(.+)$/, replacement: "/app/lib/$1" },
+    { find: "#src-extra", replacement: "/extra" },
+  ];
+  const config = { resolve: { alias: aliases } };
+  packageImportsOverKitAlias().config(config);
+  expect(config.resolve.alias).toEqual(aliases.slice(2));
+});
+
+test("missing aliases and object aliases remain usable", () => {
+  const plugin = packageImportsOverKitAlias();
+  plugin.config({});
+  const config = { resolve: { alias: { $lib: "/lib" } } };
+  plugin.config(config);
+  expect(config.resolve.alias).toEqual({ $lib: "/lib" });
+});

package/src/result.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "vite-plus/test";
+import { Ok, Err, tryCatch, tryCatchAsync } from "#src/result.ts";
+
+describe("Ok", () => {
+  it("creates a success result with ok: true", () => {
+    const result = Ok(42);
+    expect(result.ok).toBe(true);
+  });
+
+  it("holds the provided value", () => {
+    const result = Ok("hello");
+    if (result.ok) {
+      expect(result.value).toBe("hello");
+    }
+  });
+
+  it("works with object values", () => {
+    const data = { id: 1, name: "test" };
+    const result = Ok(data);
+    if (result.ok) {
+      expect(result.value).toEqual(data);
+    }
+  });
+
+  it("works with null value", () => {
+    const result = Ok(null);
+    if (result.ok) {
+      expect(result.value).toBeNull();
+    }
+  });
+});
+
+describe("Err", () => {
+  it("creates a failure result with ok: false", () => {
+    const result = Err(new Error("boom"));
+    expect(result.ok).toBe(false);
+  });
+
+  it("holds the provided error", () => {
+    const err = new Error("something failed");
+    const result = Err(err);
+    if (!result.ok) {
+      expect(result.error).toBe(err);
+    }
+  });
+
+  it("works with string errors", () => {
+    const result = Err("custom error string");
+    if (!result.ok) {
+      expect(result.error).toBe("custom error string");
+    }
+  });
+
+  it("works with custom error objects", () => {
+    const result = Err({ code: 404, message: "Not found" });
+    if (!result.ok) {
+      expect(result.error).toEqual({ code: 404, message: "Not found" });
+    }
+  });
+});
+
+describe("tryCatch", () => {
+  it("returns Ok when function succeeds", () => {
+    const result = tryCatch(() => 42);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(42);
+    }
+  });
+
+  it("returns Err when function throws an Error", () => {
+    const result = tryCatch(() => {
+      throw new Error("fail");
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe("fail");
+    }
+  });
+
+  it("wraps a thrown non-Error value in an Error", () => {
+    const result = tryCatch(() => {
+      throw "string error";
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error.message).toBe("string error");
+    }
+  });
+
+  it("wraps a thrown number in an Error", () => {
+    const result = tryCatch(() => {
+      throw 42;
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error.message).toBe("42");
+    }
+  });
+
+  it("works with a function returning an object", () => {
+    const result = tryCatch(() => ({ a: 1, b: 2 }));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual({ a: 1, b: 2 });
+    }
+  });
+});
+
+describe("tryCatchAsync", () => {
+  it("returns Ok when async function resolves", async () => {
+    const result = await tryCatchAsync(async () => "resolved");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe("resolved");
+    }
+  });
+
+  it("returns Err when async function rejects with an Error", async () => {
+    const result = await tryCatchAsync(async () => {
+      throw new Error("async fail");
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe("async fail");
+    }
+  });
+
+  it("wraps a rejected non-Error value in an Error", async () => {
+    const result = await tryCatchAsync(async () => {
+      throw "rejected string";
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error.message).toBe("rejected string");
+    }
+  });
+
+  it("works with async functions returning objects", async () => {
+    const result = await tryCatchAsync(async () => ({ data: [1, 2, 3] }));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual({ data: [1, 2, 3] });
+    }
+  });
+});

package/src/result.ts

@@ -0,0 +1,29 @@
+// Lightweight Result type for typed error handling
+
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+export function Ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+export function Err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+// Wrap a synchronous function that might throw
+export function tryCatch<T>(fn: () => T): Result<T> {
+  try {
+    return Ok(fn());
+  } catch (e) {
+    return Err(e instanceof Error ? e : new Error(String(e)));
+  }
+}
+
+// Wrap an async function that might throw
+export async function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T>> {
+  try {
+    return Ok(await fn());
+  } catch (e) {
+    return Err(e instanceof Error ? e : new Error(String(e)));
+  }
+}

package/src/string.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect } from "vite-plus/test";
+import {
+  slugify,
+  generateSlug,
+  buildSearchParams,
+  parseJSON,
+  parseCommaSeparatedList,
+  matchesQuery,
+} from "#src/string.ts";
+
+describe("slugify", () => {
+  it("lowercases the text", () => {
+    expect(slugify("Hello World")).toBe("hello-world");
+  });
+
+  it("replaces spaces with hyphens", () => {
+    expect(slugify("foo bar baz")).toBe("foo-bar-baz");
+  });
+
+  it("removes special characters", () => {
+    expect(slugify("Hello, World!")).toBe("hello-world");
+  });
+
+  it("collapses multiple spaces into a single hyphen", () => {
+    expect(slugify("foo  bar")).toBe("foo-bar");
+  });
+
+  it("collapses multiple hyphens into one", () => {
+    expect(slugify("foo---bar")).toBe("foo-bar");
+  });
+
+  it("handles an empty string", () => {
+    expect(slugify("")).toBe("");
+  });
+
+  it("preserves existing hyphens", () => {
+    expect(slugify("hello-world")).toBe("hello-world");
+  });
+});
+
+describe("generateSlug", () => {
+  it("lowercases text", () => {
+    expect(generateSlug("Hello World")).toBe("hello-world");
+  });
+
+  it("replaces non-alphanumeric characters with hyphens", () => {
+    expect(generateSlug("Hello, World!")).toBe("hello-world");
+  });
+
+  it("strips leading and trailing hyphens", () => {
+    expect(generateSlug("!hello world!")).toBe("hello-world");
+  });
+
+  it("collapses runs of non-alphanumeric characters to a single hyphen", () => {
+    expect(generateSlug("foo   ---   bar")).toBe("foo-bar");
+  });
+
+  it("handles an empty string", () => {
+    expect(generateSlug("")).toBe("");
+  });
+
+  it("handles strings that are all special characters", () => {
+    expect(generateSlug("!!!")).toBe("");
+  });
+
+  it("preserves numbers", () => {
+    expect(generateSlug("Article 42")).toBe("article-42");
+  });
+});
+
+describe("buildSearchParams", () => {
+  it("returns empty string when no params", () => {
+    expect(buildSearchParams({})).toBe("");
+  });
+
+  it("omits undefined values", () => {
+    expect(buildSearchParams({ a: "1", b: undefined })).toBe("?a=1");
+  });
+
+  it("returns empty string when all values are undefined", () => {
+    expect(buildSearchParams({ a: undefined, b: undefined })).toBe("");
+  });
+
+  it("builds a query string from a single param", () => {
+    expect(buildSearchParams({ page: "1" })).toBe("?page=1");
+  });
+
+  it("builds a query string from multiple params", () => {
+    const result = buildSearchParams({ page: "1", limit: "10" });
+    expect(result).toBe("?page=1&limit=10");
+  });
+
+  it("URL-encodes values with special characters", () => {
+    const result = buildSearchParams({ q: "hello world" });
+    expect(result).toBe("?q=hello%20world");
+  });
+
+  it("encodes special characters in values", () => {
+    const result = buildSearchParams({ filter: "name=test" });
+    expect(result).toContain("filter=");
+    expect(result).toContain("name");
+  });
+});
+
+describe("parseJSON", () => {
+  it("parses a valid JSON string", () => {
+    expect(parseJSON('{"key":"value"}')).toEqual({ key: "value" });
+  });
+
+  it("returns undefined for invalid JSON", () => {
+    expect(parseJSON("not json")).toBeUndefined();
+  });
+
+  it("returns undefined for an empty string", () => {
+    expect(parseJSON("")).toBeUndefined();
+  });
+
+  it("parses a JSON array", () => {
+    expect(parseJSON("[1,2,3]")).toEqual([1, 2, 3]);
+  });
+
+  it("parses a JSON number", () => {
+    expect(parseJSON("42")).toBe(42);
+  });
+
+  it("parses a JSON boolean", () => {
+    expect(parseJSON("true")).toBe(true);
+  });
+
+  it("returns undefined for truncated JSON", () => {
+    expect(parseJSON('{"key":')).toBeUndefined();
+  });
+
+  it("accepts a type parameter for typed output", () => {
+    type User = { name: string; age: number };
+    const result = parseJSON<User>('{"name":"Alice","age":30}');
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
+});
+
+describe("parseCommaSeparatedList", () => {
+  it("splits a comma-separated string into an array", () => {
+    expect(parseCommaSeparatedList("a,b,c")).toEqual(["a", "b", "c"]);
+  });
+
+  it("trims whitespace from each item", () => {
+    expect(parseCommaSeparatedList("a , b , c")).toEqual(["a", "b", "c"]);
+  });
+
+  it("filters out empty items", () => {
+    expect(parseCommaSeparatedList("a,,b")).toEqual(["a", "b"]);
+  });
+
+  it("returns an empty array for undefined", () => {
+    expect(parseCommaSeparatedList(undefined)).toEqual([]);
+  });
+
+  it("returns an empty array for an empty string", () => {
+    expect(parseCommaSeparatedList("")).toEqual([]);
+  });
+
+  it("returns a single-item array for a string with no commas", () => {
+    expect(parseCommaSeparatedList("hello")).toEqual(["hello"]);
+  });
+
+  it("handles commas at the start and end", () => {
+    expect(parseCommaSeparatedList(",a,b,")).toEqual(["a", "b"]);
+  });
+});
+
+describe("matchesQuery", () => {
+  it("matches a plain substring", () => {
+    expect(matchesQuery("Agency glue post 001", "glue")).toBe(true);
+  });
+
+  it("matches every word wherever it sits, not one run of characters", () => {
+    expect(matchesQuery("Agency glue post 001", "agency post")).toBe(true);
+  });
+
+  it("rejects a query whose second word is absent", () => {
+    expect(matchesQuery("Agency glue post 001", "agency draft")).toBe(false);
+  });
+
+  it("ignores case", () => {
+    expect(matchesQuery("Agency Glue", "AGENCY glue")).toBe(true);
+  });
+
+  it("ignores accents on both sides", () => {
+    expect(matchesQuery("São Paulo", "sao")).toBe(true);
+    expect(matchesQuery("Sao Paulo", "são")).toBe(true);
+  });
+
+  it("matches everything on a blank query", () => {
+    expect(matchesQuery("anything", "")).toBe(true);
+    expect(matchesQuery("anything", "   ")).toBe(true);
+  });
+
+  it("ignores the spacing around the words", () => {
+    expect(matchesQuery("Agency glue post", "  post   agency ")).toBe(true);
+  });
+
+  it("finds nothing in an empty haystack", () => {
+    expect(matchesQuery("", "post")).toBe(false);
+  });
+});

package/src/string.ts

@@ -0,0 +1,71 @@
+/** Convert text to URL-safe slug */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .trim();
+}
+
+/** Generate a URL-safe slug (strips non-alphanumeric, trims hyphens) */
+export function generateSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/** Build query string from params, omitting undefined values */
+export function buildSearchParams(params: Record<string, string | undefined>): string {
+  const entries = Object.entries(params).filter(
+    (entry): entry is [string, string] => entry[1] !== undefined,
+  );
+  if (entries.length === 0) return "";
+  return `?${entries.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&")}`;
+}
+
+/** Safely parse JSON string, returning undefined on failure */
+export function parseJSON<T = unknown>(raw: string): T | undefined {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Split comma-separated string into trimmed, non-empty array */
+export function parseCommaSeparatedList(text: string | undefined): string[] {
+  if (!text) return [];
+  return text
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** Lowercase and strip accents, so a search for "sao" reaches "São". */
+function foldForSearch(text: string): string {
+  return text
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase();
+}
+
+/**
+ * True when every word of `query` appears somewhere in `haystack`, accents and case ignored. An empty or blank query matches everything.
+ */
+
+/*
+ * WHY word by word and not one substring test: a list page joins the fields it searches into one string, so a plain `includes` makes the field order part of
+ */
+
+/*
+ * the query. On a set titled "Agency glue post 001", typing "agency post" matched nothing, which reads as the search being broken rather than strict.
+ */
+export function matchesQuery(haystack: string, query: string): boolean {
+  const words = foldForSearch(query).split(/\s+/).filter(Boolean);
+  if (words.length === 0) return true;
+  const target = foldForSearch(haystack);
+  return words.every((word) => target.includes(word));
+}

package/src/testimonials/render-content.ts

@@ -0,0 +1,21 @@
+// Safe converter for testimonial content stored with **bold** markdown.
+// Escapes HTML, then replaces **...** with <strong>...</strong>.
+// Output is intended for {@html ...} or dangerouslySetInnerHTML.
+
+const HTML_ESCAPES: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+function escapeHtml(input: string): string {
+  return input.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
+}
+
+export function renderTestimonialContent(content: string | null | undefined): string {
+  if (!content) return "";
+  const escaped = escapeHtml(content);
+  return escaped.replace(/\*\*([^*]+?)\*\*/g, "<strong>$1</strong>");
+}

package/src/testimonials/server.ts

@@ -0,0 +1,47 @@
+import type {
+  PublicCollectionResponse,
+  PublicTestimonial,
+  CollectionStat,
+} from "#src/testimonials/types.js";
+
+export const DEFAULT_TESTIMONIALS_BASE_URL = "https://app.upsys-consulting.com";
+
+export type FetchPublicTestimonialsOptions = {
+  baseUrl?: string;
+  locale?: "en" | "fr";
+  layout?: string;
+  fetchImpl?: typeof fetch;
+};
+
+export async function fetchPublicTestimonialCollection(
+  token: string,
+  opts: FetchPublicTestimonialsOptions = {},
+): Promise<PublicCollectionResponse | null> {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const baseUrl = (opts.baseUrl ?? DEFAULT_TESTIMONIALS_BASE_URL).replace(/\/$/, "");
+  const params = new URLSearchParams();
+  if (opts.locale) params.set("locale", opts.locale);
+  if (opts.layout) params.set("layout", opts.layout);
+  const query = params.toString();
+  const url = `${baseUrl}/api/testimonials/public/${encodeURIComponent(token)}${query ? `?${query}` : ""}`;
+
+  const response = await fetchImpl(url);
+  if (!response.ok) return null;
+  return (await response.json()) as PublicCollectionResponse;
+}
+
+export async function fetchPublicTestimonials(
+  token: string,
+  opts: FetchPublicTestimonialsOptions = {},
+): Promise<PublicTestimonial[]> {
+  const data = await fetchPublicTestimonialCollection(token, opts);
+  return data?.testimonials ?? [];
+}
+
+export async function fetchPublicTestimonialStats(
+  token: string,
+  opts: FetchPublicTestimonialsOptions = {},
+): Promise<CollectionStat[]> {
+  const data = await fetchPublicTestimonialCollection(token, opts);
+  return data?.collection.stats ?? [];
+}

package/src/testimonials/types.ts

@@ -0,0 +1,35 @@
+export type CollectionLayout = "grid" | "carousel" | "compact" | "highlight";
+
+export type CollectionStat = {
+  number: string;
+  labelEn: string;
+  labelFr: string;
+};
+
+export type PublicTestimonial = {
+  id: string;
+  authorName: string;
+  authorRole: string | null;
+  authorCompany: string | null;
+  authorPhotoUrl: string | null;
+  content: string;
+  /** Curated pull-quote for surfaces with room for a line or two. Null when unset. */
+  excerpt: string | null;
+  rating: number | null;
+  videoUrl: string | null;
+  locale: "en" | "fr";
+  tags: string[];
+  isFeatured: boolean;
+  createdAt: string;
+};
+
+export type PublicCollectionResponse = {
+  collection: {
+    id: string;
+    name: string;
+    layout: CollectionLayout;
+    isPublic: boolean;
+    stats: CollectionStat[];
+  };
+  testimonials: PublicTestimonial[];
+};