@hexclave/shared 1.0.2 → 1.0.5

package/src/utils/html.tsx

@@ -0,0 +1,60 @@
+import { templateIdentity } from "./strings";
+
+export function escapeHtml(unsafe: string): string {
+  return `${unsafe}`
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+import.meta.vitest?.test("escapeHtml", ({ expect }) => {
+  // Test with empty string
+  expect(escapeHtml("")).toBe("");
+
+  // Test with string without special characters
+  expect(escapeHtml("hello world")).toBe("hello world");
+
+  // Test with special characters
+  expect(escapeHtml("<div>")).toBe("&lt;div&gt;");
+  expect(escapeHtml("a & b")).toBe("a &amp; b");
+  expect(escapeHtml('a "quoted" string')).toBe("a &quot;quoted&quot; string");
+  expect(escapeHtml("it's a test")).toBe("it&#039;s a test");
+
+  // Test with multiple special characters
+  expect(escapeHtml("<a href=\"test\">It's a link</a>")).toBe(
+    "&lt;a href=&quot;test&quot;&gt;It&#039;s a link&lt;/a&gt;"
+  );
+});
+
+export function html(strings: TemplateStringsArray, ...values: any[]): string {
+  return templateIdentity(strings, ...values.map(v => escapeHtml(`${v}`)));
+}
+import.meta.vitest?.test("html", ({ expect }) => {
+  // Test with no interpolation
+  expect(html`simple string`).toBe("simple string");
+
+  // Test with string interpolation
+  expect(html`Hello, ${"world"}!`).toBe("Hello, world!");
+
+  // Test with number interpolation
+  expect(html`Count: ${42}`).toBe("Count: 42");
+
+  // Test with HTML special characters in interpolated values
+  expect(html`<div>${"<script>"}</div>`).toBe("<div>&lt;script&gt;</div>");
+
+  // Test with multiple interpolations
+  expect(html`${1} + ${2} = ${"<3"}`).toBe("1 + 2 = &lt;3");
+
+  // Test with object interpolation
+  const obj = { toString: () => "<object>" };
+  expect(html`Object: ${obj}`).toBe("Object: &lt;object&gt;");
+});
+
+export function htmlToText(untrustedHtml: string): string {
+
+  const doc = new DOMParser().parseFromString(untrustedHtml, 'text/html');
+
+  return doc.body.textContent;
+
+}

package/src/utils/http.tsx

@@ -0,0 +1,91 @@
+import { decodeBase64, encodeBase64, isBase64 } from "./bytes";
+
+export const HTTP_METHODS = {
+  "GET": {
+    safe: true,
+    idempotent: true,
+  },
+  "POST": {
+    safe: false,
+    idempotent: false,
+  },
+  "PUT": {
+    safe: false,
+    idempotent: true,
+  },
+  "DELETE": {
+    safe: false,
+    idempotent: true,
+  },
+  "PATCH": {
+    safe: false,
+    idempotent: false,
+  },
+  "OPTIONS": {
+    safe: true,
+    idempotent: true,
+  },
+  "HEAD": {
+    safe: true,
+    idempotent: true,
+  },
+  "TRACE": {
+    safe: true,
+    idempotent: true,
+  },
+  "CONNECT": {
+    safe: false,
+    idempotent: false,
+  },
+} as const;
+export type HttpMethod = keyof typeof HTTP_METHODS;
+
+export function decodeBasicAuthorizationHeader(value: string): [string, string] | null {
+  const [type, encoded, ...rest] = value.split(' ');
+  if (rest.length > 0) return null;
+  if (!encoded) return null;
+  if (type !== 'Basic') return null;
+  if (!isBase64(encoded)) return null;
+  const decoded = new TextDecoder().decode(decodeBase64(encoded));
+  const split = decoded.split(':');
+  return [split[0], split.slice(1).join(':')];
+}
+import.meta.vitest?.test("decodeBasicAuthorizationHeader", ({ expect }) => {
+  // Test with valid Basic Authorization header
+  const username = "user";
+  const password = "pass";
+  const encoded = encodeBasicAuthorizationHeader(username, password);
+  expect(decodeBasicAuthorizationHeader(encoded)).toEqual([username, password]);
+
+  // Test with password containing colons
+  const complexPassword = "pass:with:colons";
+  const encodedComplex = encodeBasicAuthorizationHeader(username, complexPassword);
+  expect(decodeBasicAuthorizationHeader(encodedComplex)).toEqual([username, complexPassword]);
+
+  // Test with invalid headers
+  expect(decodeBasicAuthorizationHeader("NotBasic dXNlcjpwYXNz")).toBe(null); // Wrong type
+  expect(decodeBasicAuthorizationHeader("Basic")).toBe(null); // Missing encoded part
+  expect(decodeBasicAuthorizationHeader("Basic not-base64")).toBe(null); // Not base64
+  expect(decodeBasicAuthorizationHeader("Basic dXNlcjpwYXNz extra")).toBe(null); // Extra parts
+});
+
+export function encodeBasicAuthorizationHeader(id: string, password: string): string {
+  if (id.includes(':')) throw new Error("Basic authorization header id cannot contain ':'");
+  return `Basic ${encodeBase64(new TextEncoder().encode(`${id}:${password}`))}`;
+}
+import.meta.vitest?.test("encodeBasicAuthorizationHeader", ({ expect }) => {
+  // Test with simple username and password
+  const encoded = encodeBasicAuthorizationHeader("user", "pass");
+  expect(encoded).toMatch(/^Basic [A-Za-z0-9+/=]+$/); // Should start with "Basic " followed by base64
+
+  // Test with empty password
+  const encodedEmptyPass = encodeBasicAuthorizationHeader("user", "");
+  expect(encodedEmptyPass).toMatch(/^Basic [A-Za-z0-9+/=]+$/);
+
+  // Test with password containing special characters
+  const encodedSpecialChars = encodeBasicAuthorizationHeader("user", "p@ss!w0rd");
+  expect(encodedSpecialChars).toMatch(/^Basic [A-Za-z0-9+/=]+$/);
+
+  // Test with username containing colon should throw
+  expect(() => encodeBasicAuthorizationHeader("user:name", "pass")).toThrow();
+});

package/src/utils/ips.tsx

@@ -0,0 +1,47 @@
+import ipRegex from "ip-regex";
+
+export type Ipv4Address = `${number}.${number}.${number}.${number}`;
+export type Ipv6Address = string;
+
+export function isIpAddress(ip: string) {
+  return ipRegex({ exact: true }).test(ip);
+}
+import.meta.vitest?.test("isIpAddress", ({ expect }) => {
+  // Test valid IPv4 addresses
+  expect(isIpAddress("192.168.1.1")).toBe(true);
+  expect(isIpAddress("127.0.0.1")).toBe(true);
+  expect(isIpAddress("0.0.0.0")).toBe(true);
+  expect(isIpAddress("255.255.255.255")).toBe(true);
+
+  // Test valid IPv6 addresses
+  expect(isIpAddress("::1")).toBe(true);
+  expect(isIpAddress("2001:db8::")).toBe(true);
+  expect(isIpAddress("2001:db8:85a3:8d3:1319:8a2e:370:7348")).toBe(true);
+
+  // Test invalid IP addresses
+  expect(isIpAddress("")).toBe(false);
+  expect(isIpAddress("not an ip")).toBe(false);
+  expect(isIpAddress("256.256.256.256")).toBe(false);
+  expect(isIpAddress("192.168.1")).toBe(false);
+  expect(isIpAddress("192.168.1.1.1")).toBe(false);
+  expect(isIpAddress("2001:db8::xyz")).toBe(false);
+});
+
+export function assertIpAddress(ip: string): asserts ip is Ipv4Address | Ipv6Address {
+  if (!isIpAddress(ip)) {
+    throw new Error(`Invalid IP address: ${ip}`);
+  }
+}
+import.meta.vitest?.test("assertIpAddress", ({ expect }) => {
+  // Test with valid IPv4 address
+  expect(() => assertIpAddress("192.168.1.1")).not.toThrow();
+
+  // Test with valid IPv6 address
+  expect(() => assertIpAddress("::1")).not.toThrow();
+
+  // Test with invalid IP addresses
+  expect(() => assertIpAddress("")).toThrow("Invalid IP address: ");
+  expect(() => assertIpAddress("not an ip")).toThrow("Invalid IP address: not an ip");
+  expect(() => assertIpAddress("256.256.256.256")).toThrow("Invalid IP address: 256.256.256.256");
+  expect(() => assertIpAddress("192.168.1")).toThrow("Invalid IP address: 192.168.1");
+});

package/src/utils/json.tsx

@@ -0,0 +1,200 @@
+import { Result } from "./results";
+
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };
+
+export type ReadonlyJson =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly ReadonlyJson[]
+  | { readonly [key: string]: ReadonlyJson };
+
+export function isJsonSerializable(value: unknown): value is Json {
+  switch (typeof value) {
+    case "object": {
+      if (value === null) return true;
+      if (Array.isArray(value)) return value.every(isJsonSerializable);
+      return Object.keys(value).every(k => typeof k === "string") && Object.values(value).every(isJsonSerializable);
+    }
+    case "string":
+    case "number":
+    case "boolean": {
+      return true;
+    }
+    default: {
+      return false;
+    }
+  }
+}
+import.meta.vitest?.test("isJsonSerializable", ({ expect }) => {
+  // Test primitive values
+  expect(isJsonSerializable(null)).toBe(true);
+  expect(isJsonSerializable(true)).toBe(true);
+  expect(isJsonSerializable(false)).toBe(true);
+  expect(isJsonSerializable(123)).toBe(true);
+  expect(isJsonSerializable("string")).toBe(true);
+
+  // Test arrays
+  expect(isJsonSerializable([])).toBe(true);
+  expect(isJsonSerializable([1, 2, 3])).toBe(true);
+  expect(isJsonSerializable(["a", "b", "c"])).toBe(true);
+  expect(isJsonSerializable([1, "a", true, null])).toBe(true);
+  expect(isJsonSerializable([1, [2, 3], { a: "b" }])).toBe(true);
+
+  // Test objects
+  expect(isJsonSerializable({})).toBe(true);
+  expect(isJsonSerializable({ a: 1, b: 2 })).toBe(true);
+  expect(isJsonSerializable({ a: "string", b: true, c: null })).toBe(true);
+  expect(isJsonSerializable({ a: [1, 2, 3], b: { c: "d" } })).toBe(true);
+
+  // Test invalid JSON values
+  expect(isJsonSerializable(undefined)).toBe(false);
+  expect(isJsonSerializable(() => {})).toBe(false);
+  expect(isJsonSerializable(Symbol())).toBe(false);
+  expect(isJsonSerializable(BigInt(123))).toBe(false);
+
+  // Test arrays with invalid JSON values
+  expect(isJsonSerializable([1, undefined, 3])).toBe(false);
+  expect(isJsonSerializable([1, () => {}, 3])).toBe(false);
+
+  // Test objects with invalid JSON values
+  expect(isJsonSerializable({ a: 1, b: undefined })).toBe(false);
+  expect(isJsonSerializable({ a: 1, b: () => {} })).toBe(false);
+});
+
+export function parseJson(json: string): Result<Json> {
+  return Result.fromThrowing(() => JSON.parse(json));
+}
+import.meta.vitest?.test("parseJson", ({ expect }) => {
+  // Test valid JSON strings
+  const nullResult = parseJson("null");
+  expect(nullResult.status).toBe("ok");
+  if (nullResult.status === "ok") {
+    expect(nullResult.data).toBe(null);
+  }
+
+  const trueResult = parseJson("true");
+  expect(trueResult.status).toBe("ok");
+  if (trueResult.status === "ok") {
+    expect(trueResult.data).toBe(true);
+  }
+
+  const numberResult = parseJson("123");
+  expect(numberResult.status).toBe("ok");
+  if (numberResult.status === "ok") {
+    expect(numberResult.data).toBe(123);
+  }
+
+  const stringResult = parseJson('"string"');
+  expect(stringResult.status).toBe("ok");
+  if (stringResult.status === "ok") {
+    expect(stringResult.data).toBe("string");
+  }
+
+  const emptyArrayResult = parseJson("[]");
+  expect(emptyArrayResult.status).toBe("ok");
+  if (emptyArrayResult.status === "ok") {
+    expect(emptyArrayResult.data).toEqual([]);
+  }
+
+  const arrayResult = parseJson("[1,2,3]");
+  expect(arrayResult.status).toBe("ok");
+  if (arrayResult.status === "ok") {
+    expect(arrayResult.data).toEqual([1, 2, 3]);
+  }
+
+  const emptyObjectResult = parseJson("{}");
+  expect(emptyObjectResult.status).toBe("ok");
+  if (emptyObjectResult.status === "ok") {
+    expect(emptyObjectResult.data).toEqual({});
+  }
+
+  const objectResult = parseJson('{"a":1,"b":"string"}');
+  expect(objectResult.status).toBe("ok");
+  if (objectResult.status === "ok") {
+    expect(objectResult.data).toEqual({ a: 1, b: "string" });
+  }
+
+  // Test invalid JSON strings
+  expect(parseJson("").status).toBe("error");
+  expect(parseJson("undefined").status).toBe("error");
+  expect(parseJson("{").status).toBe("error");
+  expect(parseJson('{"a":1,}').status).toBe("error");
+  expect(parseJson("function(){}").status).toBe("error");
+});
+
+export function stringifyJson(json: Json): Result<string> {
+  return Result.fromThrowing(() => JSON.stringify(json));
+}
+import.meta.vitest?.test("stringifyJson", ({ expect }) => {
+  // Test primitive values
+  const nullResult = stringifyJson(null);
+  expect(nullResult.status).toBe("ok");
+  if (nullResult.status === "ok") {
+    expect(nullResult.data).toBe("null");
+  }
+
+  const trueResult = stringifyJson(true);
+  expect(trueResult.status).toBe("ok");
+  if (trueResult.status === "ok") {
+    expect(trueResult.data).toBe("true");
+  }
+
+  const numberResult = stringifyJson(123);
+  expect(numberResult.status).toBe("ok");
+  if (numberResult.status === "ok") {
+    expect(numberResult.data).toBe("123");
+  }
+
+  const stringResult = stringifyJson("string");
+  expect(stringResult.status).toBe("ok");
+  if (stringResult.status === "ok") {
+    expect(stringResult.data).toBe('"string"');
+  }
+
+  // Test arrays
+  const emptyArrayResult = stringifyJson([]);
+  expect(emptyArrayResult.status).toBe("ok");
+  if (emptyArrayResult.status === "ok") {
+    expect(emptyArrayResult.data).toBe("[]");
+  }
+
+  const arrayResult = stringifyJson([1, 2, 3]);
+  expect(arrayResult.status).toBe("ok");
+  if (arrayResult.status === "ok") {
+    expect(arrayResult.data).toBe("[1,2,3]");
+  }
+
+  // Test objects
+  const emptyObjectResult = stringifyJson({});
+  expect(emptyObjectResult.status).toBe("ok");
+  if (emptyObjectResult.status === "ok") {
+    expect(emptyObjectResult.data).toBe("{}");
+  }
+
+  const objectResult = stringifyJson({ a: 1, b: "string" });
+  expect(objectResult.status).toBe("ok");
+  if (objectResult.status === "ok") {
+    expect(objectResult.data).toBe('{"a":1,"b":"string"}');
+  }
+
+  // Test nested structures
+  const nested = { a: [1, 2, 3], b: { c: "d" } };
+  const nestedResult = stringifyJson(nested);
+  expect(nestedResult.status).toBe("ok");
+  if (nestedResult.status === "ok") {
+    expect(nestedResult.data).toBe('{"a":[1,2,3],"b":{"c":"d"}}');
+  }
+
+  // Test circular references (should error)
+  const circular: any = { a: 1 };
+  circular.self = circular;
+  expect(stringifyJson(circular).status).toBe("error");
+});

package/src/utils/jsx-editable-transpiler.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from 'vitest';
+import { transpileJsxForEditing, convertSentinelTokensToComments } from './jsx-editable-transpiler';
+
+describe('transpileJsxForEditing', () => {
+  it('should wrap simple JSX text nodes with __Editable', () => {
+    const source = `
+export function EmailTemplate() {
+  return <div>Hello World!</div>;
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    expect(result.code).toContain('__Editable');
+    expect(result.code).toContain('Hello World!');
+    expect(Object.keys(result.editableRegions).length).toBeGreaterThan(0);
+
+    // Check that the editable region has the expected metadata
+    const region = Object.values(result.editableRegions)[0];
+    expect(region.originalText).toBe('Hello World!');
+    expect(region.sourceFile).toBe('template');
+    expect(region.parentElement.tagName).toBe('div');
+  });
+
+  it('should handle multiple text nodes in the same element', () => {
+    const source = `
+export function EmailTemplate({ name }) {
+  return <div>Hello, {name}! Welcome to our platform.</div>;
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    // Should have 2 editable regions (text before and after the expression)
+    const regions = Object.values(result.editableRegions);
+    expect(regions.length).toBe(2);
+
+    const texts = regions.map(r => r.originalText);
+    expect(texts).toContain('Hello, ');
+    expect(texts).toContain('! Welcome to our platform.');
+  });
+
+  it('should skip whitespace-only text nodes', () => {
+    const source = `
+export function EmailTemplate() {
+  return (
+    <div>
+      <span>Text</span>
+    </div>
+  );
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    // Should only have 1 editable region (the "Text" in span)
+    const regions = Object.values(result.editableRegions);
+    expect(regions.length).toBe(1);
+    expect(regions[0].originalText).toBe('Text');
+  });
+
+  it('should track occurrence count for duplicate text', () => {
+    const source = `
+export function EmailTemplate() {
+  return (
+    <div>
+      <p>Click here</p>
+      <p>Click here</p>
+    </div>
+  );
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    const regions = Object.values(result.editableRegions);
+    expect(regions.length).toBe(2);
+
+    // Both should have occurrenceCount of 2
+    expect(regions[0].occurrenceCount).toBe(2);
+    expect(regions[1].occurrenceCount).toBe(2);
+
+    // They should have different occurrence indices
+    expect(regions[0].occurrenceIndex).toBe(1);
+    expect(regions[1].occurrenceIndex).toBe(2);
+  });
+
+  it('should capture JSX path correctly', () => {
+    const source = `
+export function EmailTemplate() {
+  return (
+    <Container>
+      <Section>
+        <Text>Hello</Text>
+      </Section>
+    </Container>
+  );
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    const region = Object.values(result.editableRegions)[0];
+    expect(region.jsxPath).toContain('EmailTemplate');
+    expect(region.jsxPath).toContain('Container');
+    expect(region.jsxPath).toContain('Section');
+    expect(region.jsxPath).toContain('Text');
+  });
+
+  it('should capture parent element props', () => {
+    const source = `
+export function EmailTemplate() {
+  return <Text className="heading" style={{ color: 'red' }}>Title</Text>;
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    const region = Object.values(result.editableRegions)[0];
+    expect(region.parentElement.tagName).toBe('Text');
+    expect(region.parentElement.props.className).toBe('heading');
+  });
+
+  it('should inject __Editable component definition', () => {
+    const source = `
+export function EmailTemplate() {
+  return <div>Test</div>;
+}
+`;
+    const result = transpileJsxForEditing(source, { sourceFile: 'template' });
+
+    expect(result.code).toContain('function __Editable');
+    expect(result.code).toContain('STACK_EDITABLE_START');
+    expect(result.code).toContain('STACK_EDITABLE_END');
+  });
+});
+
+describe('convertSentinelTokensToComments', () => {
+  it('should convert start tokens to HTML comments', () => {
+    const html = '<div>⟦STACK_EDITABLE_START:e0⟧Hello⟦STACK_EDITABLE_END:e0⟧</div>';
+    const result = convertSentinelTokensToComments(html);
+
+    expect(result).toBe('<div><!-- STACK_EDITABLE_START e0 -->Hello<!-- STACK_EDITABLE_END e0 --></div>');
+  });
+
+  it('should handle multiple editable regions', () => {
+    const html = '<div>⟦STACK_EDITABLE_START:e0⟧Hello⟦STACK_EDITABLE_END:e0⟧ ⟦STACK_EDITABLE_START:e1⟧World⟦STACK_EDITABLE_END:e1⟧</div>';
+    const result = convertSentinelTokensToComments(html);
+
+    expect(result).toContain('<!-- STACK_EDITABLE_START e0 -->');
+    expect(result).toContain('<!-- STACK_EDITABLE_END e0 -->');
+    expect(result).toContain('<!-- STACK_EDITABLE_START e1 -->');
+    expect(result).toContain('<!-- STACK_EDITABLE_END e1 -->');
+  });
+
+  it('should leave regular HTML unchanged', () => {
+    const html = '<div><p>Hello World</p></div>';
+    const result = convertSentinelTokensToComments(html);
+
+    expect(result).toBe(html);
+  });
+});