freesail 0.0.1 → 0.1.0

package/packages/core/src/functions.ts

@@ -0,0 +1,403 @@
+/**
+ * Standard Functions Library
+ * 
+ * A2UI Standard Functions for client-side data logic.
+ * Used in template expressions like ${formatCurrency(price, 'USD')}.
+ */
+
+// =============================================================================
+// Currency Formatting
+// =============================================================================
+
+export interface CurrencyOptions {
+  locale?: string;
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+}
+
+/**
+ * Format a number as currency
+ */
+export function formatCurrency(
+  value: number, 
+  currency: string = 'USD',
+  options: CurrencyOptions = {}
+): string {
+  const {
+    locale = 'en-US',
+    minimumFractionDigits = 2,
+    maximumFractionDigits = 2,
+  } = options;
+
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+    minimumFractionDigits,
+    maximumFractionDigits,
+  }).format(value);
+}
+
+// =============================================================================
+// Number Formatting
+// =============================================================================
+
+export interface NumberOptions {
+  locale?: string;
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+  useGrouping?: boolean;
+}
+
+/**
+ * Format a number with locale-specific formatting
+ */
+export function formatNumber(
+  value: number,
+  options: NumberOptions = {}
+): string {
+  const {
+    locale = 'en-US',
+    minimumFractionDigits = 0,
+    maximumFractionDigits = 2,
+    useGrouping = true,
+  } = options;
+
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits,
+    maximumFractionDigits,
+    useGrouping,
+  }).format(value);
+}
+
+/**
+ * Format a number as a percentage
+ */
+export function formatPercent(
+  value: number,
+  options: { locale?: string; decimals?: number } = {}
+): string {
+  const { locale = 'en-US', decimals = 0 } = options;
+  
+  return new Intl.NumberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value);
+}
+
+/**
+ * Format bytes into human-readable size
+ */
+export function formatBytes(bytes: number, decimals: number = 2): string {
+  if (bytes === 0) return '0 Bytes';
+  
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(decimals))} ${sizes[i]}`;
+}
+
+// =============================================================================
+// Date Formatting
+// =============================================================================
+
+export type DateFormatStyle = 'short' | 'medium' | 'long' | 'full';
+
+export interface DateOptions {
+  locale?: string;
+  dateStyle?: DateFormatStyle;
+  timeStyle?: DateFormatStyle;
+}
+
+/**
+ * Format a date/time value
+ */
+export function formatDate(
+  value: Date | string | number,
+  options: DateOptions = {}
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  const { locale = 'en-US', dateStyle = 'medium', timeStyle } = options;
+
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle,
+    timeStyle,
+  } as Intl.DateTimeFormatOptions).format(date);
+}
+
+/**
+ * Format a date as relative time (e.g., "2 hours ago")
+ */
+export function formatRelativeTime(
+  value: Date | string | number,
+  locale: string = 'en-US'
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  const now = new Date();
+  const diffMs = date.getTime() - now.getTime();
+  const diffSecs = Math.round(diffMs / 1000);
+  const diffMins = Math.round(diffSecs / 60);
+  const diffHours = Math.round(diffMins / 60);
+  const diffDays = Math.round(diffHours / 24);
+
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+
+  if (Math.abs(diffSecs) < 60) {
+    return rtf.format(diffSecs, 'second');
+  } else if (Math.abs(diffMins) < 60) {
+    return rtf.format(diffMins, 'minute');
+  } else if (Math.abs(diffHours) < 24) {
+    return rtf.format(diffHours, 'hour');
+  } else {
+    return rtf.format(diffDays, 'day');
+  }
+}
+
+// =============================================================================
+// String Formatting
+// =============================================================================
+
+/**
+ * Pluralize a word based on count
+ */
+export function pluralize(
+  count: number,
+  singular: string,
+  plural?: string
+): string {
+  if (count === 1) return singular;
+  return plural ?? `${singular}s`;
+}
+
+/**
+ * Truncate text with ellipsis
+ */
+export function truncate(
+  text: string,
+  maxLength: number,
+  suffix: string = '...'
+): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - suffix.length) + suffix;
+}
+
+/**
+ * Capitalize the first letter of a string
+ */
+export function capitalize(text: string): string {
+  if (!text) return '';
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+/**
+ * Convert a string to title case
+ */
+export function titleCase(text: string): string {
+  return text
+    .toLowerCase()
+    .split(' ')
+    .map(word => capitalize(word))
+    .join(' ');
+}
+
+/**
+ * Format a string using named placeholders
+ */
+export function format(
+  template: string,
+  values: Record<string, unknown>
+): string {
+  return template.replace(/\{(\w+)\}/g, (_, key) => {
+    return key in values ? String(values[key]) : `{${key}}`;
+  });
+}
+
+// =============================================================================
+// Regex Functions
+// =============================================================================
+
+/**
+ * Test if a string matches a pattern
+ */
+export function regexTest(
+  text: string,
+  pattern: string,
+  flags: string = ''
+): boolean {
+  const regex = new RegExp(pattern, flags);
+  return regex.test(text);
+}
+
+/**
+ * Extract matches from a string
+ */
+export function regexMatch(
+  text: string,
+  pattern: string,
+  flags: string = ''
+): string[] {
+  const regex = new RegExp(pattern, flags);
+  const match = text.match(regex);
+  return match ? Array.from(match) : [];
+}
+
+/**
+ * Replace text using regex
+ */
+export function regexReplace(
+  text: string,
+  pattern: string,
+  replacement: string,
+  flags: string = 'g'
+): string {
+  const regex = new RegExp(pattern, flags);
+  return text.replace(regex, replacement);
+}
+
+// =============================================================================
+// Validation Functions
+// =============================================================================
+
+/**
+ * Check if a value is empty
+ */
+export function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') return Object.keys(value).length === 0;
+  return false;
+}
+
+/**
+ * Check if a string is a valid email
+ */
+export function isEmail(value: string): boolean {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(value);
+}
+
+/**
+ * Check if a string is a valid URL
+ */
+export function isUrl(value: string): boolean {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// =============================================================================
+// Array Functions
+// =============================================================================
+
+/**
+ * Get the first N items from an array
+ */
+export function take<T>(array: T[], count: number): T[] {
+  return array.slice(0, count);
+}
+
+/**
+ * Get the last N items from an array
+ */
+export function takeLast<T>(array: T[], count: number): T[] {
+  return array.slice(-count);
+}
+
+/**
+ * Join array items with a separator
+ */
+export function join(
+  array: unknown[],
+  separator: string = ', ',
+  lastSeparator?: string
+): string {
+  if (array.length === 0) return '';
+  if (array.length === 1) return String(array[0]);
+  
+  if (lastSeparator) {
+    const items = array.map(String);
+    const last = items.pop();
+    return `${items.join(separator)}${lastSeparator}${last}`;
+  }
+  
+  return array.map(String).join(separator);
+}
+
+// =============================================================================
+// Conditional Functions
+// =============================================================================
+
+/**
+ * Return value based on condition
+ */
+export function ifElse<T>(
+  condition: boolean,
+  trueValue: T,
+  falseValue: T
+): T {
+  return condition ? trueValue : falseValue;
+}
+
+/**
+ * Return first non-null/undefined value
+ */
+export function coalesce<T>(...values: (T | null | undefined)[]): T | undefined {
+  for (const value of values) {
+    if (value !== null && value !== undefined) return value;
+  }
+  return undefined;
+}
+
+// =============================================================================
+// Function Registry
+// =============================================================================
+
+/**
+ * Standard function registry for template expression evaluation
+ */
+export const standardFunctions = {
+  // Currency
+  formatCurrency,
+  
+  // Numbers
+  formatNumber,
+  formatPercent,
+  formatBytes,
+  
+  // Dates
+  formatDate,
+  formatRelativeTime,
+  
+  // Strings
+  pluralize,
+  truncate,
+  capitalize,
+  titleCase,
+  format,
+  
+  // Regex
+  regexTest,
+  regexMatch,
+  regexReplace,
+  
+  // Validation
+  isEmpty,
+  isEmail,
+  isUrl,
+  
+  // Arrays
+  take,
+  takeLast,
+  join,
+  
+  // Conditionals
+  ifElse,
+  coalesce,
+};
+
+export type StandardFunctions = typeof standardFunctions;

package/packages/core/src/index.ts

@@ -0,0 +1,214 @@
+/**
+ * Freesail Core SDK
+ * 
+ * The brain of the Freesail SDK - handles A2UX protocol,
+ * transport, state management, and standard functions.
+ */
+
+// Types
+export type {
+  A2UXComponent,
+  A2UXMessage,
+  ServerToClientMessage,
+  ClientToServerMessage,
+  CreateSurfaceMessage,
+  UpdateComponentsMessage,
+  UpdateDataModelMessage,
+  DeleteSurfaceMessage,
+  WatchSurfaceMessage,
+  UnwatchSurfaceMessage,
+  UserActionMessage,
+  WatchSurfaceResponseMessage,
+} from './types.js';
+
+export {
+  isCreateSurface,
+  isUpdateComponents,
+  isUpdateDataModel,
+  isDeleteSurface,
+  isWatchSurface,
+  isUnwatchSurface,
+  isUserAction,
+  isWatchSurfaceResponse,
+  getMessageType,
+  getSurfaceId,
+} from './types.js';
+
+// Protocol Handler
+export type {
+  ProtocolEventMap,
+  ProtocolEventHandler,
+  ProtocolHandlerOptions,
+} from './protocol.js';
+
+export { A2UXProtocolHandler } from './protocol.js';
+
+// Parser
+export type {
+  ParseResult,
+  ParserOptions,
+} from './parser.js';
+
+export {
+  JSONStreamParser,
+  SSEParser,
+  parseTemplateExpression,
+} from './parser.js';
+
+// Transport
+export type {
+  TransportOptions,
+  TransportEventMap,
+  TransportEventHandler,
+  ConnectionState,
+} from './transport.js';
+
+export { FreesailTransport } from './transport.js';
+
+// Store
+export type {
+  Surface,
+  StoreEventMap,
+  StoreEventHandler,
+} from './store.js';
+
+export { SurfaceStore } from './store.js';
+
+// Functions
+export {
+  formatCurrency,
+  formatNumber,
+  formatPercent,
+  formatBytes,
+  formatDate,
+  formatRelativeTime,
+  pluralize,
+  truncate,
+  capitalize,
+  titleCase,
+  format,
+  regexTest,
+  regexMatch,
+  regexReplace,
+  isEmpty,
+  isEmail,
+  isUrl,
+  take,
+  takeLast,
+  join,
+  ifElse,
+  coalesce,
+  standardFunctions,
+} from './functions.js';
+
+export type { StandardFunctions, CurrencyOptions, NumberOptions, DateOptions } from './functions.js';
+
+// =============================================================================
+// Convenience: Freesail Client
+// =============================================================================
+
+import { FreesailTransport, type TransportOptions } from './transport.js';
+import { A2UXProtocolHandler, type ProtocolHandlerOptions } from './protocol.js';
+import { SurfaceStore } from './store.js';
+import type { A2UXMessage, UserActionMessage, WatchSurfaceResponseMessage } from './types.js';
+
+export interface FreesailClientOptions extends TransportOptions {
+  /** Protocol handler options */
+  protocol?: Omit<ProtocolHandlerOptions, 'store'>;
+}
+
+/**
+ * FreesailClient is the main entry point for client applications.
+ * It combines transport, protocol handling, and state management.
+ */
+export class FreesailClient {
+  private transport: FreesailTransport;
+  private protocol: A2UXProtocolHandler;
+  private store: SurfaceStore;
+
+  constructor(options: FreesailClientOptions) {
+    this.store = new SurfaceStore();
+    
+    this.protocol = new A2UXProtocolHandler({
+      ...options.protocol,
+      store: this.store,
+    });
+
+    this.transport = new FreesailTransport(options);
+
+    // Wire up transport messages to protocol handler
+    this.transport.on('message', (message: A2UXMessage) => {
+      this.protocol.processMessage(message);
+    });
+
+    // Wire up watch callbacks to transport
+    this.store.on('watchCallback', (response: WatchSurfaceResponseMessage) => {
+      this.transport.sendWatchResponse(response);
+    });
+  }
+
+  /**
+   * Connect to the server
+   */
+  async connect(): Promise<void> {
+    await this.transport.connect();
+  }
+
+  /**
+   * Disconnect from the server
+   */
+  disconnect(): void {
+    this.transport.disconnect();
+    this.protocol.destroy();
+  }
+
+  /**
+   * Send a user action
+   */
+  async sendAction(
+    surfaceId: string,
+    action: string,
+    context?: Record<string, unknown>
+  ): Promise<void> {
+    // Use full context from store if not provided
+    const fullContext = context ?? this.store.getDataModel(surfaceId) ?? {};
+    
+    const message: UserActionMessage = {
+      userAction: {
+        surfaceId,
+        action,
+        context: fullContext,
+      }
+    };
+
+    await this.transport.sendAction(message);
+  }
+
+  /**
+   * Get the surface store
+   */
+  getStore(): SurfaceStore {
+    return this.store;
+  }
+
+  /**
+   * Get the protocol handler
+   */
+  getProtocol(): A2UXProtocolHandler {
+    return this.protocol;
+  }
+
+  /**
+   * Get the transport
+   */
+  getTransport(): FreesailTransport {
+    return this.transport;
+  }
+
+  /**
+   * Check if connected
+   */
+  get isConnected(): boolean {
+    return this.transport.isConnected;
+  }
+}