@htlkg/astro 0.0.1

package/src/utils/hydration.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  serializeForHydration,
+  deserializeFromHydration,
+  createHydrationScript,
+  createHydrationScripts,
+  createIslandProps,
+  mergeProps,
+} from './hydration';
+
+describe('Hydration Utilities', () => {
+  describe('serializeForHydration', () => {
+    it('should serialize basic data', () => {
+      const data = { id: 1, name: 'Test' };
+      const serialized = serializeForHydration(data);
+      
+      expect(serialized).toBe('{"id":1,"name":"Test"}');
+    });
+
+    it('should handle dates', () => {
+      const date = new Date('2024-01-01T00:00:00.000Z');
+      const data = { date };
+      const serialized = serializeForHydration(data);
+      
+      // JSON.stringify converts dates to ISO strings by default
+      expect(serialized).toContain('"2024-01-01T00:00:00.000Z"');
+    });
+
+    it('should handle undefined', () => {
+      const data = { value: undefined };
+      const serialized = serializeForHydration(data);
+      
+      expect(serialized).toContain('"__type":"undefined"');
+    });
+
+    it('should skip functions', () => {
+      const data = { fn: () => {}, value: 'test' };
+      const serialized = serializeForHydration(data);
+      
+      expect(serialized).not.toContain('fn');
+      expect(serialized).toContain('"value":"test"');
+    });
+  });
+
+  describe('deserializeFromHydration', () => {
+    it('should deserialize basic data', () => {
+      const json = '{"id":1,"name":"Test"}';
+      const data = deserializeFromHydration(json);
+      
+      expect(data).toEqual({ id: 1, name: 'Test' });
+    });
+
+    it('should handle date strings', () => {
+      const json = '{"date":"2024-01-01T00:00:00.000Z"}';
+      const data = deserializeFromHydration<{ date: string }>(json);
+      
+      // Dates are serialized as ISO strings
+      expect(data.date).toBe('2024-01-01T00:00:00.000Z');
+    });
+
+    it('should restore undefined', () => {
+      const json = '{"value":{"__type":"undefined"}}';
+      const data = deserializeFromHydration<{ value: undefined }>(json);
+      
+      expect(data.value).toBeUndefined();
+    });
+  });
+
+  describe('createHydrationScript', () => {
+    it('should create hydration script', () => {
+      const data = { id: 1, name: 'Test' };
+      const script = createHydrationScript('myData', data);
+      
+      expect(script).toBe('window.myData = {"id":1,"name":"Test"};');
+    });
+  });
+
+  describe('createHydrationScripts', () => {
+    it('should create multiple hydration scripts', () => {
+      const data = {
+        user: { id: 1, name: 'User' },
+        config: { theme: 'dark' },
+      };
+      
+      const scripts = createHydrationScripts(data);
+      
+      expect(scripts).toContain('window.user = {"id":1,"name":"User"};');
+      expect(scripts).toContain('window.config = {"theme":"dark"};');
+    });
+  });
+
+  describe('createIslandProps', () => {
+    it('should remove functions from props', () => {
+      const props = {
+        id: 1,
+        name: 'Test',
+        onClick: () => {},
+        onSubmit: () => {},
+      };
+      
+      const cleanProps = createIslandProps(props);
+      
+      expect(cleanProps).toEqual({ id: 1, name: 'Test' });
+    });
+
+    it('should remove undefined values', () => {
+      const props = {
+        id: 1,
+        name: 'Test',
+        optional: undefined,
+      };
+      
+      const cleanProps = createIslandProps(props);
+      
+      expect(cleanProps).toEqual({ id: 1, name: 'Test' });
+    });
+
+    it('should keep null values', () => {
+      const props = {
+        id: 1,
+        value: null,
+      };
+      
+      const cleanProps = createIslandProps(props);
+      
+      expect(cleanProps).toEqual({ id: 1, value: null });
+    });
+  });
+
+  describe('mergeProps', () => {
+    it('should merge server and client props', () => {
+      const serverProps = { id: 1, name: 'Server', value: 'old' };
+      const clientProps = { value: 'new', extra: 'data' };
+      
+      const merged = mergeProps(serverProps, clientProps);
+      
+      expect(merged).toEqual({
+        id: 1,
+        name: 'Server',
+        value: 'new',
+        extra: 'data',
+      });
+    });
+
+    it('should not mutate original props', () => {
+      const serverProps = { id: 1, name: 'Server' };
+      const clientProps = { name: 'Client' };
+      
+      mergeProps(serverProps, clientProps);
+      
+      expect(serverProps.name).toBe('Server');
+    });
+  });
+});

package/src/utils/hydration.ts

@@ -0,0 +1,151 @@
+/**
+ * Hydration Utilities
+ * 
+ * Helper functions for Vue component hydration in Astro.
+ */
+
+/**
+ * Serialize data for client-side hydration
+ * Safely handles dates, functions, and circular references
+ */
+export function serializeForHydration<T>(data: T): string {
+  return JSON.stringify(data, (key, value) => {
+    // Skip functions
+    if (typeof value === 'function') {
+      return undefined;
+    }
+    
+    // Handle undefined
+    if (value === undefined) {
+      return { __type: 'undefined' };
+    }
+    
+    return value;
+  });
+}
+
+/**
+ * Deserialize data on client-side
+ */
+export function deserializeFromHydration<T>(json: string): T {
+  return JSON.parse(json, (key, value) => {
+    // Handle undefined
+    if (value && value.__type === 'undefined') {
+      return undefined;
+    }
+    
+    return value;
+  });
+}
+
+/**
+ * Create hydration script for Vue components
+ * 
+ * @example
+ * ```astro
+ * <script set:html={createHydrationScript('userData', user)} />
+ * ```
+ */
+export function createHydrationScript(
+  variableName: string,
+  data: any
+): string {
+  const serialized = serializeForHydration(data);
+  return `window.${variableName} = ${serialized};`;
+}
+
+/**
+ * Create multiple hydration scripts
+ */
+export function createHydrationScripts(
+  data: Record<string, any>
+): string {
+  return Object.entries(data)
+    .map(([key, value]) => createHydrationScript(key, value))
+    .join('\n');
+}
+
+/**
+ * Get hydrated data on client-side
+ */
+export function getHydratedData<T>(variableName: string): T | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  
+  const data = (window as any)[variableName];
+  return data ? deserializeFromHydration(JSON.stringify(data)) : null;
+}
+
+/**
+ * Check if component should hydrate
+ */
+export function shouldHydrate(
+  strategy: 'load' | 'idle' | 'visible' | 'media' | 'only',
+  options?: {
+    mediaQuery?: string;
+  }
+): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+  
+  switch (strategy) {
+    case 'load':
+      return true;
+    
+    case 'idle':
+      return 'requestIdleCallback' in window;
+    
+    case 'visible':
+      return 'IntersectionObserver' in window;
+    
+    case 'media':
+      if (!options?.mediaQuery) return false;
+      return window.matchMedia(options.mediaQuery).matches;
+    
+    case 'only':
+      return false;
+    
+    default:
+      return true;
+  }
+}
+
+/**
+ * Create Vue island props
+ * Prepares props for Vue component islands
+ */
+export function createIslandProps<T extends Record<string, any>>(
+  props: T
+): T {
+  // Remove functions and non-serializable values
+  const cleanProps: any = {};
+  
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof value === 'function') {
+      continue;
+    }
+    
+    if (value === undefined) {
+      continue;
+    }
+    
+    cleanProps[key] = value;
+  }
+  
+  return cleanProps;
+}
+
+/**
+ * Merge server and client props
+ */
+export function mergeProps<T extends Record<string, any>>(
+  serverProps: T,
+  clientProps: Partial<T>
+): T {
+  return {
+    ...serverProps,
+    ...clientProps,
+  };
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @htlkg/pages - Utilities
+ * 
+ * Helper functions for Astro pages.
+ */
+
+export * from './ssr';
+export * from './static';
+export * from './hydration';

package/src/utils/ssr.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  getServerData,
+  isServerSide,
+  getRequestHeaders,
+  getQueryParams,
+  setResponseHeaders,
+  setCacheControl,
+  getClientIP,
+  isMobileDevice,
+} from './ssr';
+
+describe('SSR Utilities', () => {
+  describe('getServerData', () => {
+    it('should return data from successful fetch', async () => {
+      const mockAstro = {} as any;
+      const fetcher = vi.fn().mockResolvedValue({ id: 1, name: 'Test' });
+      
+      const result = await getServerData(mockAstro, fetcher);
+      
+      expect(result).toEqual({ id: 1, name: 'Test' });
+      expect(fetcher).toHaveBeenCalledOnce();
+    });
+
+    it('should return null on error without redirect', async () => {
+      const mockAstro = {} as any;
+      const fetcher = vi.fn().mockRejectedValue(new Error('Fetch failed'));
+      
+      const result = await getServerData(mockAstro, fetcher);
+      
+      expect(result).toBeNull();
+    });
+
+    it('should return default value on error', async () => {
+      const mockAstro = {} as any;
+      const fetcher = vi.fn().mockRejectedValue(new Error('Fetch failed'));
+      const defaultValue = { id: 0, name: 'Default' };
+      
+      const result = await getServerData(mockAstro, fetcher, { defaultValue });
+      
+      expect(result).toEqual(defaultValue);
+    });
+  });
+
+  describe('isServerSide', () => {
+    it('should return true when no client header', () => {
+      const mockAstro = {
+        request: {
+          headers: new Map(),
+        },
+      } as any;
+      
+      expect(isServerSide(mockAstro)).toBe(true);
+    });
+
+    it('should return false when client header present', () => {
+      const headers = new Map();
+      headers.set('x-astro-client', 'true');
+      
+      const mockAstro = {
+        request: { headers },
+      } as any;
+      
+      expect(isServerSide(mockAstro)).toBe(false);
+    });
+  });
+
+  describe('getRequestHeaders', () => {
+    it('should convert headers to object', () => {
+      const headers = new Map();
+      headers.set('content-type', 'application/json');
+      headers.set('authorization', 'Bearer token');
+      
+      const mockAstro = {
+        request: { headers },
+      } as any;
+      
+      const result = getRequestHeaders(mockAstro);
+      
+      expect(result).toEqual({
+        'content-type': 'application/json',
+        'authorization': 'Bearer token',
+      });
+    });
+  });
+
+  describe('getQueryParams', () => {
+    it('should extract query parameters', () => {
+      const mockAstro = {
+        request: {
+          url: 'https://example.com/page?foo=bar&baz=qux',
+        },
+      } as any;
+      
+      const result = getQueryParams(mockAstro);
+      
+      expect(result).toEqual({
+        foo: 'bar',
+        baz: 'qux',
+      });
+    });
+
+    it('should return empty object when no params', () => {
+      const mockAstro = {
+        request: {
+          url: 'https://example.com/page',
+        },
+      } as any;
+      
+      const result = getQueryParams(mockAstro);
+      
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('setResponseHeaders', () => {
+    it('should set response headers', () => {
+      const headers = new Map();
+      const mockAstro = {
+        response: {
+          headers: {
+            set: vi.fn((key, value) => headers.set(key, value)),
+          },
+        },
+      } as any;
+      
+      setResponseHeaders(mockAstro, {
+        'X-Custom': 'value',
+        'X-Another': 'test',
+      });
+      
+      expect(mockAstro.response.headers.set).toHaveBeenCalledWith('X-Custom', 'value');
+      expect(mockAstro.response.headers.set).toHaveBeenCalledWith('X-Another', 'test');
+    });
+  });
+
+  describe('setCacheControl', () => {
+    it('should set cache control with max-age', () => {
+      const mockAstro = {
+        response: {
+          headers: {
+            set: vi.fn(),
+          },
+        },
+      } as any;
+      
+      setCacheControl(mockAstro, { maxAge: 3600, public: true });
+      
+      expect(mockAstro.response.headers.set).toHaveBeenCalledWith(
+        'Cache-Control',
+        'public, max-age=3600'
+      );
+    });
+
+    it('should set cache control with all options', () => {
+      const mockAstro = {
+        response: {
+          headers: {
+            set: vi.fn(),
+          },
+        },
+      } as any;
+      
+      setCacheControl(mockAstro, {
+        maxAge: 3600,
+        sMaxAge: 7200,
+        staleWhileRevalidate: 86400,
+        public: true,
+      });
+      
+      expect(mockAstro.response.headers.set).toHaveBeenCalledWith(
+        'Cache-Control',
+        'public, max-age=3600, s-maxage=7200, stale-while-revalidate=86400'
+      );
+    });
+  });
+
+  describe('getClientIP', () => {
+    it('should get IP from x-forwarded-for', () => {
+      const headers = new Map();
+      headers.set('x-forwarded-for', '192.168.1.1, 10.0.0.1');
+      
+      const mockAstro = {
+        request: { headers },
+      } as any;
+      
+      expect(getClientIP(mockAstro)).toBe('192.168.1.1');
+    });
+
+    it('should get IP from x-real-ip', () => {
+      const headers = new Map();
+      headers.set('x-real-ip', '192.168.1.1');
+      
+      const mockAstro = {
+        request: { headers },
+      } as any;
+      
+      expect(getClientIP(mockAstro)).toBe('192.168.1.1');
+    });
+
+    it('should return null when no IP headers', () => {
+      const mockAstro = {
+        request: {
+          headers: new Map(),
+        },
+      } as any;
+      
+      expect(getClientIP(mockAstro)).toBeNull();
+    });
+  });
+
+  describe('isMobileDevice', () => {
+    it('should detect mobile user agent', () => {
+      const headers = new Map();
+      headers.set('user-agent', 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)');
+      
+      const mockAstro = {
+        request: { headers },
+      } as any;
+      
+      expect(isMobileDevice(mockAstro)).toBe(true);
+    });
+
+    it('should detect desktop user agent', () => {
+      const headers = new Map();
+      headers.set('user-agent', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)');
+      
+      const mockAstro = {
+        request: { headers },
+      } as any;
+      
+      expect(isMobileDevice(mockAstro)).toBe(false);
+    });
+  });
+});

package/src/utils/ssr.ts

@@ -0,0 +1,139 @@
+/**
+ * SSR Utilities
+ * 
+ * Helper functions for server-side rendering in Astro pages.
+ */
+
+import type { AstroGlobal } from 'astro';
+
+/**
+ * Get server-side data with error handling
+ * 
+ * @example
+ * ```ts
+ * const data = await getServerData(Astro, async () => {
+ *   return await fetchBrand(brandId);
+ * });
+ * ```
+ */
+export async function getServerData<T>(
+  astro: AstroGlobal,
+  fetcher: () => Promise<T>,
+  options: {
+    redirectOnError?: string;
+    defaultValue?: T;
+  } = {}
+): Promise<T | null> {
+  try {
+    return await fetcher();
+  } catch (error) {
+    console.error('[SSR] Error fetching data:', error);
+    
+    if (options.redirectOnError) {
+      return astro.redirect(options.redirectOnError) as any;
+    }
+    
+    return options.defaultValue ?? null;
+  }
+}
+
+/**
+ * Check if request is from server-side
+ */
+export function isServerSide(astro: AstroGlobal): boolean {
+  return !astro.request.headers.get('x-astro-client');
+}
+
+/**
+ * Get request headers as object
+ */
+export function getRequestHeaders(astro: AstroGlobal): Record<string, string> {
+  const headers: Record<string, string> = {};
+  astro.request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  return headers;
+}
+
+/**
+ * Get query parameters from URL
+ */
+export function getQueryParams(astro: AstroGlobal): Record<string, string> {
+  const params: Record<string, string> = {};
+  const searchParams = new URL(astro.request.url).searchParams;
+  
+  searchParams.forEach((value, key) => {
+    params[key] = value;
+  });
+  
+  return params;
+}
+
+/**
+ * Set response headers
+ */
+export function setResponseHeaders(
+  astro: AstroGlobal,
+  headers: Record<string, string>
+): void {
+  Object.entries(headers).forEach(([key, value]) => {
+    astro.response.headers.set(key, value);
+  });
+}
+
+/**
+ * Set cache control headers
+ */
+export function setCacheControl(
+  astro: AstroGlobal,
+  options: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    public?: boolean;
+  }
+): void {
+  const directives: string[] = [];
+  
+  if (options.public) {
+    directives.push('public');
+  } else {
+    directives.push('private');
+  }
+  
+  if (options.maxAge !== undefined) {
+    directives.push(`max-age=${options.maxAge}`);
+  }
+  
+  if (options.sMaxAge !== undefined) {
+    directives.push(`s-maxage=${options.sMaxAge}`);
+  }
+  
+  if (options.staleWhileRevalidate !== undefined) {
+    directives.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
+  }
+  
+  astro.response.headers.set('Cache-Control', directives.join(', '));
+}
+
+/**
+ * Get client IP address
+ */
+export function getClientIP(astro: AstroGlobal): string | null {
+  const headers = astro.request.headers;
+  
+  return (
+    headers.get('x-forwarded-for')?.split(',')[0].trim() ||
+    headers.get('x-real-ip') ||
+    headers.get('cf-connecting-ip') ||
+    null
+  );
+}
+
+/**
+ * Check if request is from mobile device
+ */
+export function isMobileDevice(astro: AstroGlobal): boolean {
+  const userAgent = astro.request.headers.get('user-agent') || '';
+  return /mobile|android|iphone|ipad|phone/i.test(userAgent);
+}