@heyramzi/utils 0.0.0-stage → 1.12.0

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[];
+};

package/src/timing.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vite-plus/test";
+import { debounce, throttle, sleep } from "#src/timing.ts";
+
+describe("debounce", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("does not call the function before the delay", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("calls the function after the delay", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("only calls once when invoked multiple times within the delay", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    debounced();
+    debounced();
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("resets the timer on each call", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(50);
+    debounced();
+    vi.advanceTimersByTime(50);
+
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards arguments to the wrapped function", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced("arg1", "arg2");
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledWith("arg1", "arg2");
+  });
+
+  it("can be called multiple times after each delay period", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(100);
+    debounced();
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("throttle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("calls the function immediately on the first invocation", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled();
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call the function again within the limit", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled();
+    throttled();
+    throttled();
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows a second call after the limit period has passed", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled();
+    vi.advanceTimersByTime(100);
+    throttled();
+
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("forwards arguments to the wrapped function", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled("hello", 42);
+    expect(fn).toHaveBeenCalledWith("hello", 42);
+  });
+});
+
+describe("sleep", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns a Promise", () => {
+    const result = sleep(100);
+    expect(result).toBeInstanceOf(Promise);
+    vi.runAllTimers();
+  });
+
+  it("resolves after the given number of milliseconds", async () => {
+    let resolved = false;
+    sleep(500).then(() => {
+      resolved = true;
+    });
+
+    expect(resolved).toBe(false);
+    vi.advanceTimersByTime(499);
+    await Promise.resolve(); // flush microtasks
+    expect(resolved).toBe(false);
+
+    vi.advanceTimersByTime(1);
+    await Promise.resolve();
+    expect(resolved).toBe(true);
+  });
+
+  it("resolves with undefined", async () => {
+    const promise = sleep(10);
+    vi.advanceTimersByTime(10);
+    const result = await promise;
+    expect(result).toBeUndefined();
+  });
+});

package/src/timing.ts

@@ -0,0 +1,28 @@
+export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
+  fn: T,
+  delay: number,
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout>;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), delay);
+  };
+}
+
+export function throttle<T extends (...args: Parameters<T>) => ReturnType<T>>(
+  fn: T,
+  limit: number,
+): (...args: Parameters<T>) => void {
+  let inThrottle = false;
+  return (...args: Parameters<T>) => {
+    if (!inThrottle) {
+      fn(...args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/vite.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "vite";
+
+export declare function packageImportsOverKitAlias(): Plugin;
+
+/**
+ * Vite plugin: before the dev server binds, kill whatever is already listening on the configured port and take the port back, instead of letting Vite drift to the next free
+ */
+
+/*
+ * port. Dev-only, macOS/Linux only, no-op on Windows or any failure.
+ */
+export declare function reclaimPort(): Plugin;