@africode/core 5.0.0

package/core/state.js

@@ -0,0 +1,242 @@
+/**
+ * AfriCode Reactive State System
+ * 
+ * A lightweight, Proxy-based reactive state management system
+ * following the African Fractal philosophy - simple at the core,
+ * powerful through composition.
+ * 
+ * @module core/state
+ */
+
+// Store for all subscribers per state
+const stateSubscribers = new WeakMap();
+
+// Track nested proxies to avoid duplicates
+const proxyCache = new WeakMap();
+
+/**
+ * Creates a deeply reactive state object using Proxy
+ * State changes automatically notify all subscribers
+ * 
+ * @param {Object} initialState - The initial state object
+ * @returns {Proxy} A reactive proxy of the state
+ * 
+ * @example
+ * const state = createReactiveState({ count: 0, user: { name: 'Amara' } });
+ * subscribe(() => console.log('State changed!'));
+ * state.count++; // Logs: "State changed!"
+ */
+export function createReactiveState(initialState) {
+  // Return cached proxy if already created
+  if (proxyCache.has(initialState)) {
+    return proxyCache.get(initialState);
+  }
+
+  const handler = {
+    get(target, property, receiver) {
+      const value = Reflect.get(target, property, receiver);
+
+      // Recursively wrap nested objects
+      if (value !== null && typeof value === 'object') {
+        return createReactiveState(value);
+      }
+
+      return value;
+    },
+
+    set(target, property, value, receiver) {
+      const oldValue = Reflect.get(target, property, receiver);
+
+      // Only notify if value actually changed
+      if (oldValue !== value) {
+        const result = Reflect.set(target, property, value, receiver);
+
+        if (result) {
+          notifySubscribers(receiver, value, oldValue, property);
+        }
+
+        return result;
+      }
+
+      return true;
+    },
+
+    deleteProperty(target, property) {
+      const oldValue = Reflect.get(target, property);
+      const result = Reflect.deleteProperty(target, property);
+
+      if (result) {
+        const proxy = proxyCache.get(target);
+        notifySubscribers(proxy, undefined, oldValue, property);
+      }
+
+      return result;
+    }
+  };
+
+  const proxy = new Proxy(initialState, handler);
+  proxyCache.set(initialState, proxy);
+
+  return proxy;
+}
+
+/**
+ * Subscribe to state changes
+ * 
+ * @param {Proxy} state - The reactive state to subscribe to
+ * @param {Function} callback - Function to call when state changes
+ * @returns {Function} Unsubscribe function
+ * 
+ * @example
+ * const state = createReactiveState({ count: 0 });
+ * const unsubscribe = subscribe(state, () => updateUI());
+ * // Later: unsubscribe();
+ */
+export function subscribe(state, callback) {
+  if (!stateSubscribers.has(state)) {
+    stateSubscribers.set(state, new Set());
+  }
+  
+  const subscribers = stateSubscribers.get(state);
+  subscribers.add(callback);
+
+  // Return unsubscribe function
+  return () => {
+    subscribers.delete(callback);
+  };
+}
+
+/**
+ * Notify all subscribers of state change
+ * Uses microtask queue for batched updates
+ */
+function notifySubscribers(state, newValue, oldValue, property) {
+  // For testing, make synchronous. In production, use microtask
+  const subscribers = stateSubscribers.get(state);
+  if (!subscribers) {return;}
+  
+  subscribers.forEach(callback => {
+    try {
+      callback(newValue, oldValue, property);
+    } catch (error) {
+      console.error('[AfriCode State] Subscriber error:', error);
+    }
+  });
+}
+
+/**
+ * Create a computed value that updates when dependencies change
+ * 
+ * @param {Function} computeFn - Function that computes the derived value
+ * @returns {Function} Getter function for the computed value
+ * 
+ * @example
+ * const state = createReactiveState({ price: 100, quantity: 2 });
+ * const total = computed(() => state.price * state.quantity);
+ * console.log(total()); // 200
+ */
+export function computed(computeFn) {
+  let cachedValue;
+  let isDirty = true;
+
+  subscribe(() => {
+    isDirty = true;
+  });
+
+  return () => {
+    if (isDirty) {
+      cachedValue = computeFn();
+      isDirty = false;
+    }
+    return cachedValue;
+  };
+}
+
+/**
+ * Batch multiple state changes into a single notification
+ * 
+ * @param {Function} updateFn - Function containing multiple state updates
+ * 
+ * @example
+ * batch(() => {
+ *   state.name = 'Kwame';
+ *   state.age = 25;
+ *   state.country = 'Ghana';
+ * }); // Only one notification
+ */
+export function batch(state, updateFn) {
+  const subscribers = stateSubscribers.get(state) || new Set();
+  const originalSubscribers = new Set(subscribers);
+  subscribers.clear();
+
+  try {
+    updateFn();
+  } finally {
+    originalSubscribers.forEach(sub => subscribers.add(sub));
+    notifySubscribers(state);
+  }
+}
+
+/**
+ * Create a simple signal (getter/setter pair)
+ * 
+ * @param {*} initialValue - The initial value
+ * @returns {[Function, Function]} [getter, setter]
+ * 
+ * @example
+ * const [count, setCount] = createSignal(0);
+ * console.log(count()); // 0
+ * setCount(5);
+ * console.log(count()); // 5
+ */
+export function createSignal(initialValue) {
+  let value = initialValue;
+  const signalSubscribers = new Set();
+
+  const getter = () => {
+    return value;
+  };
+
+  const setter = (newValue) => {
+    if (value !== newValue) {
+      value = typeof newValue === 'function' ? newValue(value) : newValue;
+      signalSubscribers.forEach(fn => fn());
+      notifySubscribers();
+    }
+  };
+
+  // Allow effects to subscribe to this signal
+  getter.subscribe = (fn) => {
+    signalSubscribers.add(fn);
+    return () => signalSubscribers.delete(fn);
+  };
+
+  return [getter, setter];
+}
+
+/**
+ * Create an effect that runs when reactive dependencies change
+ * 
+ * @param {Function} effectFn - The effect function to run
+ * @returns {Function} Cleanup function
+ * 
+ * @example
+ * const [count, setCount] = createSignal(0);
+ * createEffect(() => console.log('Count is:', count()));
+ */
+export function createEffect(effectFn) {
+  // Run immediately
+  effectFn();
+  // Subscribe to future changes
+  return subscribe(effectFn);
+}
+
+// Default export for convenience
+export default {
+  createReactiveState,
+  subscribe,
+  computed,
+  batch,
+  createSignal,
+  createEffect
+};

package/core/store.d.ts

@@ -0,0 +1,122 @@
+/**
+ * AfriCode Store (Global State) - TypeScript Definitions
+ */
+
+/**
+ * Global store interface
+ */
+export interface GlobalStore {
+  /** Current theme (light/dark/custom) */
+  theme: string;
+  
+  /** Current language code (en/sw/fr/ar/am/yo) */
+  language: string;
+  
+  /** Current user (if authenticated) */
+  user?: {
+    id: string;
+    name: string;
+    email: string;
+    roles?: string[];
+  };
+  
+  /** App-level notifications */
+  notifications?: Array<{
+    id: string;
+    message: string;
+    type: 'info' | 'success' | 'warning' | 'error';
+    timestamp: number;
+  }>;
+  
+  /** Global loading state */
+  isLoading?: boolean;
+  
+  /** Global error state */
+  error?: Error | null;
+  
+  /** Additional properties */
+  [key: string]: any;
+}
+
+/**
+ * Store actions interface
+ */
+export interface StoreActions {
+  /** Set theme */
+  setTheme(theme: string): void;
+  
+  /** Set language */
+  setLanguage(language: string): void;
+  
+  /** Set user */
+  setUser(user: GlobalStore['user']): void;
+  
+  /** Clear user (logout) */
+  clearUser(): void;
+  
+  /** Show notification */
+  notify(message: string, type?: string): void;
+  
+  /** Set loading state */
+  setLoading(isLoading: boolean): void;
+  
+  /** Set error */
+  setError(error: Error | null): void;
+  
+  /** Clear error */
+  clearError(): void;
+  
+  /** Additional actions */
+  [key: string]: any;
+}
+
+/**
+ * Global reactive store object
+ */
+export const store: GlobalStore;
+
+/**
+ * Store action methods
+ */
+export const actions: StoreActions;
+
+/**
+ * Subscribe to store changes
+ */
+export function watchStore<K extends keyof GlobalStore>(
+  key: K,
+  callback: (value: GlobalStore[K]) => void
+): () => void; // Unsubscribe function
+
+/**
+ * Watch for user changes
+ */
+export function watchUser(
+  callback: (user: GlobalStore['user']) => void
+): () => void;
+
+/**
+ * Watch for theme changes
+ */
+export function watchTheme(
+  callback: (theme: string) => void
+): () => void;
+
+/**
+ * Watch for language changes
+ */
+export function watchLanguage(
+  callback: (lang: string) => void
+): () => void;
+
+/**
+ * Reset store to initial state
+ */
+export function resetStore(): void;
+
+/**
+ * Get store snapshot
+ */
+export function getStoreSnapshot(): Readonly<GlobalStore>;
+
+export default store;

package/core/store.js

@@ -0,0 +1,61 @@
+/**
+ * AfriCode Global Store
+ * 
+ * Centralized state container for the application UI.
+ * Powered by the core reactive engine.
+ * 
+ * @module core/store
+ */
+
+import { createReactiveState } from './state.js';
+
+// Initial default state
+const initialState = {
+    theme: 'light',        // Top-level theme
+    language: 'en',        // Top-level language
+    ui: {
+        sidebarCollapsed: false,
+        theme: 'dark', // 'dark', 'light', 'system'
+        activePage: 'home'
+    },
+    user: {
+        name: 'Guest',
+        permissions: []
+    },
+    config: {
+        animationsEnabled: true,
+        soundEnabled: false
+    }
+};
+
+// Create the global store
+export const store = createReactiveState(initialState);
+
+// Actions (Helper functions to modify state)
+export const actions = {
+    setTheme(theme) {
+        if (['dark', 'light', 'system'].includes(theme)) {
+            store.theme = theme;
+            // Also update ui.theme for consistency
+            store.ui.theme = theme;
+        }
+    },
+
+    setLanguage(language) {
+        store.language = language;
+    },
+
+    toggleSidebar(collapsed) {
+        if (typeof collapsed === 'boolean') {
+            store.ui.sidebarCollapsed = collapsed;
+        } else {
+            store.ui.sidebarCollapsed = !store.ui.sidebarCollapsed;
+        }
+    },
+
+    setActivePage(pageName) {
+        store.ui.activePage = pageName;
+    }
+};
+
+export default { store, actions };

package/core/validation.d.ts

@@ -0,0 +1,233 @@
+/**
+ * AfriCode Validation System Type Definitions
+ *
+ * Philosophy: Strict by default. Convenient by composition. Secure early.
+ *
+ * TypeScript definitions for Zod-based validation schemas, AfriFieldBuilder,
+ * afri namespace, and normalizeInput utility.
+ */
+
+import { z } from 'zod';
+
+// ─────────────────────────────────────────────────────────────
+// Result Types
+// ─────────────────────────────────────────────────────────────
+
+export interface ValidationResult<T = any> {
+  success: boolean;
+  data?: T;
+  errors?: Record<string, string>;
+}
+
+export interface FieldValidationResult {
+  success: boolean;
+  error?: string;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────
+
+export interface ValidationSchemas {
+  login: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+  }>;
+
+  register: z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodString;
+    password: z.ZodString;
+    confirmPassword: z.ZodString;
+  }>;
+
+  contact: z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodString;
+    message: z.ZodString;
+  }>;
+
+  /** User profile update — avatar_url is a strict URL, nullable */
+  userProfile: z.ZodObject<{
+    full_name: z.ZodOptional<z.ZodString>;
+    bio: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    avatar_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodEnum<['africanity', 'dark', 'light', 'system']>>;
+    language: z.ZodOptional<z.ZodString>;
+  }>;
+
+  /** Project creation/update — repository_url, demo_url are strict URLs, nullable */
+  project: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    repository_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    demo_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    is_public: z.ZodOptional<z.ZodBoolean>;
+  }>;
+
+  email: z.ZodString;
+  password: z.ZodString;
+  phone: z.ZodString;
+  url: z.ZodString;
+  required: z.ZodString;
+  positiveNumber: z.ZodNumber;
+  integer: z.ZodNumber;
+  futureDate: z.ZodDate;
+  imageFile: z.ZodType<File>;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Validation Class
+// ─────────────────────────────────────────────────────────────
+
+export declare class Validation {
+  static validate<T>(
+    schema: z.ZodSchema<T>,
+    data: unknown
+  ): ValidationResult<T>;
+
+  static validateField(
+    schema: z.ZodSchema,
+    value: unknown
+  ): FieldValidationResult;
+
+  static getFieldError(
+    validationResult: ValidationResult,
+    fieldPath: string
+  ): string | null;
+
+  static hasFieldError(
+    validationResult: ValidationResult,
+    fieldPath: string
+  ): boolean;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Rules
+// ─────────────────────────────────────────────────────────────
+
+export interface ValidationRules {
+  required: (message?: string) => z.ZodString;
+  email: (message?: string) => z.ZodString;
+  minLength: (min: number, message?: string) => z.ZodString;
+  maxLength: (max: number, message?: string) => z.ZodString;
+  pattern: (regex: RegExp, message: string) => z.ZodString;
+  numeric: (message?: string) => z.ZodString;
+  phone: (message?: string) => z.ZodString;
+  url: (message?: string) => z.ZodString;
+}
+
+// ─────────────────────────────────────────────────────────────
+// AfriFieldBuilder — Chainable field schema builder
+//
+// Strict by default. Convenient by composition.
+// ─────────────────────────────────────────────────────────────
+
+export interface AfriFieldMeta {
+  fieldType: string;
+  isNullable: boolean;
+  isOptional: boolean;
+  emptyAsNull: boolean;
+}
+
+/**
+ * Chainable field builder for AfriCode validation schemas.
+ * Wraps Zod with framework-level semantics.
+ *
+ * .emptyAsNull() does NOT alter the Zod schema itself.
+ * It marks the field for preprocessing via normalizeInput().
+ */
+export declare class AfriFieldBuilder {
+  constructor(baseSchema: z.ZodSchema, fieldType?: string);
+
+  /** Allow null as a valid value */
+  nullable(): this;
+
+  /** Allow undefined (field can be omitted) */
+  optional(): this;
+
+  /**
+   * Mark this field for empty-string-to-null conversion.
+   * Requires .nullable() to have been called first.
+   * The conversion happens in normalizeInput(), not in the Zod schema.
+   */
+  emptyAsNull(): this;
+
+  /** Set a custom error message */
+  message(message: string): this;
+
+  /** Build the final Zod schema */
+  build(): z.ZodSchema;
+
+  /** Get the metadata for this field (used by normalizeInput) */
+  getMeta(): AfriFieldMeta;
+}
+
+// ─────────────────────────────────────────────────────────────
+// afri namespace — Field factory
+// ─────────────────────────────────────────────────────────────
+
+export interface AfriNamespace {
+  /** Create a strict URL field builder. Empty strings always rejected at core. */
+  url(message?: string): AfriFieldBuilder;
+
+  /** Create a strict email field builder. */
+  email(message?: string): AfriFieldBuilder;
+
+  /** Create a string field builder. */
+  string(opts?: { min?: number; max?: number; message?: string }): AfriFieldBuilder;
+
+  /** Create a number field builder. */
+  number(opts?: { min?: number; max?: number; int?: boolean }): AfriFieldBuilder;
+
+  /** Create a phone field builder. */
+  phone(message?: string): AfriFieldBuilder;
+}
+
+export declare const afri: AfriNamespace;
+
+// ─────────────────────────────────────────────────────────────
+// Preprocessing Utilities
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Normalize input data before validation.
+ * Examines field metadata from AfriFieldBuilder instances and applies
+ * transformations like converting empty strings to null for .emptyAsNull() fields.
+ *
+ * Separation of concerns:
+ * - normalizeInput() = input adapter (flexible)
+ * - Validation.validate() = core validation (strict)
+ */
+export declare function normalizeInput(
+  fieldBuilders: Record<string, AfriFieldBuilder>,
+  data: Record<string, unknown>
+): Record<string, unknown>;
+
+/**
+ * Build a Zod object schema from a map of AfriFieldBuilder instances.
+ * Convenience method to go from builders → Zod schema in one step.
+ */
+export declare function buildSchema(
+  fieldBuilders: Record<string, AfriFieldBuilder | z.ZodSchema>
+): z.ZodObject<any>;
+
+// ─────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────
+
+export declare const schemas: ValidationSchemas;
+export declare const rules: ValidationRules;
+
+declare const validation: {
+  schemas: ValidationSchemas;
+  Validation: typeof Validation;
+  rules: ValidationRules;
+  afri: AfriNamespace;
+  AfriFieldBuilder: typeof AfriFieldBuilder;
+  normalizeInput: typeof normalizeInput;
+  buildSchema: typeof buildSchema;
+};
+
+export default validation;