@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/ssr.js

@@ -0,0 +1,339 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { errorLogger } from "./error-handling.js";
+import { processDirectives } from "./process.js";
+import { extractVariables } from "./utils.js";
+import { patternToRegex } from "stx-router";
+import { serializeSetCookie } from "./cookie-serialize.js";
+
+export class MemorySessionStore {
+  store = new Map;
+  async get(sessionId) {
+    const entry = this.store.get(sessionId);
+    if (!entry || entry.expires <= Date.now()) {
+      if (entry)
+        this.store.delete(sessionId);
+      return null;
+    }
+    return { ...entry.data };
+  }
+  async set(sessionId, data, ttlSeconds) {
+    this.store.set(sessionId, { data: { ...data }, expires: Date.now() + ttlSeconds * 1000 });
+  }
+  async delete(sessionId) {
+    this.store.delete(sessionId);
+  }
+}
+async function createSession(sessionId, ttl, store) {
+  const sessionData = {}, flashData = {}, existing = await store.get(sessionId);
+  if (existing)
+    Object.assign(sessionData, existing);
+  const session = {
+    id: sessionId,
+    data: sessionData,
+    get(key) {
+      return sessionData[key];
+    },
+    set(key, value) {
+      sessionData[key] = value;
+      saveSession();
+    },
+    delete(key) {
+      delete sessionData[key];
+      saveSession();
+    },
+    clear() {
+      Object.keys(sessionData).forEach((key) => delete sessionData[key]);
+      saveSession();
+    },
+    has(key) {
+      return key in sessionData;
+    },
+    flash(key, value) {
+      if (value !== void 0) {
+        flashData[key] = value;
+        return;
+      }
+      const val = flashData[key];
+      delete flashData[key];
+      return val;
+    },
+    regenerate() {
+      const oldId = sessionId;
+      sessionId = generateSessionId();
+      session.id = sessionId;
+      store.delete(oldId);
+      saveSession();
+    },
+    destroy() {
+      store.delete(sessionId);
+      Object.keys(sessionData).forEach((key) => delete sessionData[key]);
+    }
+  };
+  function saveSession() {
+    store.set(sessionId, { ...sessionData, __flash: flashData }, ttl);
+  }
+  saveSession();
+  return session;
+}
+function generateSessionId() {
+  return crypto.randomBytes(32).toString("hex");
+}
+function parseCookies(cookieHeader) {
+  if (!cookieHeader)
+    return {};
+  return cookieHeader.split(";").reduce((cookies, cookie) => {
+    const [name, ...valueParts] = cookie.trim().split("=");
+    if (name)
+      cookies[name] = decodeURIComponent(valueParts.join("="));
+    return cookies;
+  }, {});
+}
+function serializeCookie(name, value, options = {}) {
+  return serializeSetCookie(name, value, options);
+}
+function copyContextHeaders(from, into) {
+  for (const cookie of from.getSetCookie())
+    into.append("Set-Cookie", cookie);
+  from.forEach((value, key) => {
+    if (key.toLowerCase() !== "set-cookie")
+      into.set(key, value);
+  });
+}
+function generateCsrfToken() {
+  return crypto.randomBytes(32).toString("hex");
+}
+function verifyCsrfToken(token, sessionToken) {
+  if (!token || !sessionToken)
+    return !1;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(token), Buffer.from(sessionToken));
+  } catch {
+    return !1;
+  }
+}
+export async function render(template, data = {}, options = {}) {
+  const viewsDir = options.viewsDir || "./views", layoutsDir = options.layoutsDir || "./layouts", isPath = !template.includes("<") && !template.includes("@");
+  let templateContent, templatePath;
+  if (isPath) {
+    templatePath = path.resolve(viewsDir, template);
+    if (!templatePath.endsWith(".stx"))
+      templatePath += ".stx";
+    if (!await Bun.file(templatePath).exists())
+      return new Response(`Template not found: ${template}`, { status: 500 });
+    templateContent = await Bun.file(templatePath).text();
+  } else {
+    templateContent = template;
+    templatePath = "inline-template.stx";
+  }
+  const context = {
+    ...data,
+    props: data,
+    __filename: templatePath,
+    __dirname: path.dirname(templatePath)
+  };
+  if (options.ctx) {
+    context.csrf_token = options.ctx.csrfToken;
+    context.csrf_field = `<input type="hidden" name="_token" value="${options.ctx.csrfToken}">`;
+    context.old = options.ctx.old;
+    context.errors = options.ctx.errors;
+    context.session = options.ctx.session;
+    context.user = options.ctx.user();
+    context.isAuthenticated = options.ctx.isAuthenticated();
+  }
+  const serverScriptMatch = templateContent.match(/<script\s+server\b[^>]*>([\s\S]*?)<\/script>/i);
+  if (serverScriptMatch) {
+    const serverScript = serverScriptMatch[1];
+    templateContent = templateContent.replace(/<script\s+server\b[^>]*>[\s\S]*?<\/script>/gi, "");
+    await extractVariables(serverScript, context, templatePath);
+  }
+  const stxOptions = {
+    layoutsDir,
+    ...options.stxOptions
+  }, html = await processDirectives(templateContent, context, templatePath, stxOptions, new Set), headers = new Headers({
+    "Content-Type": "text/html; charset=utf-8"
+  });
+  if (options.ctx)
+    copyContextHeaders(options.ctx.responseHeaders, headers);
+  return new Response(html, { headers });
+}
+export function createApp(config = {}) {
+  const {
+    viewsDir = "./views",
+    layoutsDir = "./layouts",
+    defaultLayout,
+    sessionSecret = crypto.randomBytes(32).toString("hex"),
+    sessionCookieName = "stx_session",
+    sessionTtl = 86400,
+    stxOptions = {},
+    csrfCookieName = "csrf_token",
+    csrfEnabled = !0
+  } = config, store = config.sessionStore ?? new MemorySessionStore, routes = [], globalMiddleware = [];
+  function matchRoute(method, pathname) {
+    for (const route of routes) {
+      if (route.method !== method && route.method !== "*")
+        continue;
+      const { regex, params: paramNames } = patternToRegex(route.pattern), match = pathname.match(regex);
+      if (match) {
+        const params = {};
+        paramNames.forEach((name, i) => {
+          params[name] = match[i + 1];
+        });
+        return { route, params };
+      }
+    }
+    return null;
+  }
+  async function createContext(request, params) {
+    const url = new URL(request.url), cookies = parseCookies(request.headers.get("Cookie")), responseHeaders = new Headers;
+    let sessionId = cookies[sessionCookieName];
+    if (!sessionId) {
+      sessionId = generateSessionId();
+      responseHeaders.append("Set-Cookie", serializeCookie(sessionCookieName, sessionId, {
+        httpOnly: !0,
+        secure: url.protocol === "https:",
+        sameSite: "Lax",
+        path: "/",
+        maxAge: sessionTtl
+      }));
+    }
+    const session = await createSession(sessionId, sessionTtl, store);
+    let csrfToken = session.get("_csrf");
+    if (!csrfToken) {
+      csrfToken = generateCsrfToken();
+      session.set("_csrf", csrfToken);
+    }
+    const query = {};
+    url.searchParams.forEach((value, key) => {
+      query[key] = value;
+    });
+    const errors = session.flash("_errors") || {}, oldInput = session.flash("_old_input") || {};
+    return {
+      request,
+      url,
+      params,
+      query,
+      session,
+      csrfToken,
+      cookies,
+      responseHeaders,
+      errors,
+      async formData() {
+        const formData = await request.formData(), data = {};
+        formData.forEach((value, key) => {
+          data[key] = value;
+        });
+        return data;
+      },
+      async json() {
+        return await request.json();
+      },
+      setCookie(name, value, options = {}) {
+        responseHeaders.append("Set-Cookie", serializeCookie(name, value, options));
+      },
+      flash(key, value) {
+        session.flash(key, value);
+      },
+      getFlash(key) {
+        return session.flash(key);
+      },
+      old(key) {
+        return oldInput[key] || "";
+      },
+      isAuthenticated() {
+        return session.has("user");
+      },
+      user() {
+        return session.get("user");
+      }
+    };
+  }
+  const csrfMiddleware = async (ctx, next) => {
+    if (["GET", "HEAD", "OPTIONS"].includes(ctx.request.method))
+      return next();
+    if (!csrfEnabled)
+      return next();
+    const tokenFromForm = (await ctx.request.clone().formData().catch(() => new FormData)).get("_token"), tokenFromHeader = ctx.request.headers.get("X-CSRF-Token"), token = tokenFromForm || tokenFromHeader, sessionToken = ctx.session.get("_csrf");
+    if (!token || !sessionToken || !verifyCsrfToken(token, sessionToken))
+      return new Response("CSRF token mismatch", { status: 419 });
+    return next();
+  };
+  async function fetch(request) {
+    const url = new URL(request.url), method = request.method, match = matchRoute(method, url.pathname);
+    if (!match)
+      return new Response("Not Found", { status: 404 });
+    const ctx = await createContext(request, match.params), middleware = [...globalMiddleware, csrfMiddleware, ...match.route.middleware];
+    let index = 0;
+    const next = async () => {
+      if (index < middleware.length) {
+        const mw = middleware[index++];
+        return mw(ctx, next);
+      }
+      return match.route.handler(ctx);
+    };
+    try {
+      const response = await next();
+      copyContextHeaders(ctx.responseHeaders, response.headers);
+      return response;
+    } catch (error) {
+      errorLogger.log(error instanceof Error ? error : Error(String(error)), { handler: "request" }, "error");
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  }
+  function addRoute(method, pattern, handler, middleware = []) {
+    routes.push({ method, pattern, handler, middleware });
+  }
+  return {
+    fetch,
+    get(pattern, handler, middleware = []) {
+      addRoute("GET", pattern, handler, middleware);
+      return this;
+    },
+    post(pattern, handler, middleware = []) {
+      addRoute("POST", pattern, handler, middleware);
+      return this;
+    },
+    put(pattern, handler, middleware = []) {
+      addRoute("PUT", pattern, handler, middleware);
+      return this;
+    },
+    delete(pattern, handler, middleware = []) {
+      addRoute("DELETE", pattern, handler, middleware);
+      return this;
+    },
+    patch(pattern, handler, middleware = []) {
+      addRoute("PATCH", pattern, handler, middleware);
+      return this;
+    },
+    use(middleware) {
+      globalMiddleware.push(middleware);
+      return this;
+    },
+    async render(template, data = {}, ctx) {
+      return render(template, data, { viewsDir, layoutsDir, stxOptions, ctx });
+    },
+    redirect(url, status = 302) {
+      return new Response(null, {
+        status,
+        headers: { Location: url }
+      });
+    },
+    back(ctx, errors, oldInput) {
+      if (errors)
+        ctx.session.flash("_errors", errors);
+      if (oldInput)
+        ctx.session.flash("_old_input", oldInput);
+      const referer = ctx.request.headers.get("Referer") || "/";
+      return new Response(null, {
+        status: 302,
+        headers: { Location: referer }
+      });
+    },
+    listen(port = 3000) {
+      return Bun.serve({
+        port,
+        fetch
+      });
+    }
+  };
+}

package/dist/state-dir.d.ts

@@ -0,0 +1,36 @@
+/** The directory used when nothing configures one. */
+export declare const DEFAULT_STATE_DIR = ".stx";
+/** Environment variable that overrides both the config and the default. */
+export declare const STATE_DIR_ENV_VAR = "STX_DIR";
+/**
+ * Records the `stateDir` coming from `stx.config.ts`.
+ *
+ * Called by the config loader. A nullish or blank value clears it, so a config
+ * without `stateDir` cannot inherit a stale value from a previously loaded one
+ * (the dev server loads a config per app directory).
+ */
+export declare function setStateDir(dir?: string | null): void;
+/**
+ * The configured state directory, as written — relative or absolute.
+ */
+export declare function stateDirName(): string;
+/**
+ * Absolute path to a file or directory inside the state directory.
+ *
+ * An absolute state directory wins over `root`, so a framework can pin every
+ * cache to one place no matter which directory a given code path happens to
+ * resolve against.
+ */
+export declare function stateDir(root?: string, ...segments: string[]): string;
+/**
+ * Rewrites a config path that still carries the default `.stx/` prefix onto the
+ * configured state directory.
+ *
+ * The path-shaped config options (`cachePath`, `build.cacheDir`,
+ * `media.cache.directory`, `story.outDir`) default to somewhere under `.stx/`.
+ * Rather than make each one separately configurable, `stateDir` moves the whole
+ * family: anything under the default prefix follows it, and a path the user
+ * pointed somewhere else entirely is left alone.
+ */
+export declare function rebaseOntoStateDir(value: string): string;
+export declare function rebaseOntoStateDir(value: string | undefined): string | undefined;

package/dist/state-dir.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+export const DEFAULT_STATE_DIR = ".stx", STATE_DIR_ENV_VAR = "STX_DIR";
+let configuredStateDir = null;
+export function setStateDir(dir) {
+  configuredStateDir = dir?.trim() || null;
+}
+export function stateDirName() {
+  return process.env[STATE_DIR_ENV_VAR]?.trim() || configuredStateDir || DEFAULT_STATE_DIR;
+}
+export function stateDir(root = process.cwd(), ...segments) {
+  const dir = stateDirName();
+  return path.isAbsolute(dir) ? path.join(dir, ...segments) : path.join(root, dir, ...segments);
+}
+export function rebaseOntoStateDir(value) {
+  if (!value || path.isAbsolute(value))
+    return value;
+  const normalized = value.replace(/\\/g, "/");
+  if (normalized !== DEFAULT_STATE_DIR && !normalized.startsWith(`${DEFAULT_STATE_DIR}/`))
+    return value;
+  const suffix = normalized.slice(DEFAULT_STATE_DIR.length + 1);
+  return suffix ? path.join(stateDirName(), suffix) : stateDirName();
+}

package/dist/state-management.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Register a store globally.
+ */
+export declare function registerStore<T>(name: string, store: Store<T>): void;
+/**
+ * Get a registered store.
+ */
+export declare function getStore<T>(name: string): Store<T> | undefined;
+/**
+ * Check if a store is registered.
+ */
+export declare function hasStore(name: string): boolean;
+/**
+ * Get all registered store names.
+ */
+export declare function getStoreNames(): string[];
+/**
+ * Clear all registered stores.
+ */
+export declare function clearStores(): void;
+/**
+ * Create a reactive store.
+ */
+export declare function createStore<T>(initialValue: T, options?: StoreOptions<T>): Store<T>;
+/**
+ * Create a readonly store from a getter function.
+ */
+export declare function createReadonlyStore<T>(getter: () => T, options?: { name?: string }): Omit<Store<T>, 'set' | 'update' | 'reset'>;
+/**
+ * Create a computed value derived from stores.
+ */
+export declare function computed<T, S extends readonly Store<any>[]>(stores: S, compute: (...values: { [K in keyof S]: S[K] extends Store<infer V> ? V : never }) => T, options?: ComputedOptions): Store<T>;
+/**
+ * Create a typed action for a store.
+ */
+export declare function createAction<T, P extends unknown[], R>(store: Store<T>, name: string, handler: (state: T, ...params: P) => T | Promise<T>): (...params: P) => R extends Promise<unknown> ? Promise<void> : void;
+/**
+ * Create multiple actions for a store.
+ */
+export declare function createActions<T, A extends Record<string, (state: T, ...args: any[]) => T>>(store: Store<T>, actions: A): { [K in keyof A]: A[K] extends (state: T, ...args: infer P) => T ? (...args: P) => void : never };
+/**
+ * Create a selector that derives a value from a store.
+ */
+export declare function createSelector<T, R>(store: Store<T>, selector: (state: T) => R, options?: { equals?: (a: R, b: R) => boolean }): Store<R>;
+/**
+ * Create a selector with memoization.
+ */
+export declare function createMemoizedSelector<T, R>(store: Store<T>, selector: (state: T) => R, deps: (state: T) => unknown[]): Store<R>;
+/**
+ * Logging middleware for debugging.
+ */
+export declare function loggerMiddleware<T>(name?: string): StoreMiddleware<T>;
+/**
+ * Validation middleware.
+ */
+export declare function validationMiddleware<T>(validate: (value: T) => boolean | string): StoreMiddleware<T>;
+/**
+ * Immer-like middleware for immutable updates.
+ */
+export declare function immerMiddleware<T extends object>(): StoreMiddleware<T>;
+/**
+ * Throttle middleware.
+ */
+export declare function throttleMiddleware<T>(ms: number): StoreMiddleware<T>;
+/**
+ * Use a store in a template context.
+ * Returns a reactive reference that auto-updates.
+ */
+export declare function useStore<T>(nameOrStore: string | Store<T>): T;
+/**
+ * Create a store directive for use in templates.
+ */
+export declare function createStoreDirective(storeName: string): {
+  name: string
+  hasEndTag: boolean
+  handler: () => string
+};
+/**
+ * Initialize DevTools integration.
+ */
+export declare function initDevTools(): void;
+/**
+ * Define a store with state, getters, and actions.
+ *
+ * @example
+ * ```typescript
+ * // stores/counter.ts
+ * import { defineStore } from 'stx'
+ *
+ * export const counterStore = defineStore('counter', {
+ *   state: {
+ *     count: 0,
+ *     name: 'Counter'
+ *   },
+ *   getters: {
+ *     doubleCount: (state) => state.count * 2,
+ *     displayName: (state) => `${state.name}: ${state.count}`
+ *   },
+ *   actions: {
+ *     increment() { this.count++ },
+ *     decrement() { this.count-- },
+ *     incrementBy(amount: number) { this.count += amount },
+ *     async fetchCount() {
+ *       const response = await fetch('/api/count')
+ *       this.count = await response.json()
+ *     }
+ *   },
+ *   persist: true // or { storage: 'local', key: 'my-counter' }
+ * })
+ * ```
+ *
+ * Usage in components:
+ * ```html
+ * <script client>
+ * import { counterStore } from '@stores'
+ *
+ * // Access state
+ * console.log(counterStore.count) // 0
+ *
+ * // Use getters
+ * console.log(counterStore.doubleCount) // 0
+ *
+ * // Call actions
+ * counterStore.increment()
+ * counterStore.incrementBy(5)
+ *
+ * // Subscribe to changes
+ * counterStore.$subscribe((state) => {
+ *   console.log('Count changed:', state.count)
+ * })
+ *
+ * // Reset to initial state
+ * counterStore.$reset()
+ * </script>
+ * ```
+ */
+/**
+ * Define a store using a setup function (composition API style).
+ * The function receives no arguments and returns an object of signals,
+ * derived values, and action functions.
+ *
+ * ```ts
+ * defineStore('auth', () => {
+ *   const user = state(null)
+ *   const isAuthenticated = derived(() => !!user())
+ *   function login(data) { user.set(data) }
+ *   return { user, isAuthenticated, login }
+ * })
+ * ```
+ */
+export declare function defineStore<T extends Record<string, any>>(id: string, setup: () => T, options?: { persist?: boolean | { pick?: string[], storage?: string, key?: string } }): T;
+/**
+ * Define a store using an options object (options API style).
+ *
+ * ```ts
+ * defineStore('counter', {
+ *   state: () => ({ count: 0 }),
+ *   getters: { doubled: (s) => s.count * 2 },
+ *   actions: { increment() { this.count++ } },
+ * })
+ * ```
+ */
+export declare function defineStore<S extends object, G extends Record<string, (state: S) => any> = Record<string, never>, A extends Record<string, (...args: any[]) => any> = Record<string, never>,>(id: string, options: DefineStoreOptions<S, G, A>): DefinedStoreWithGettersAndActions<S, G, A>;
+/**
+ * Get a defined store by name.
+ * Used internally by the @stores import transformation.
+ */
+export declare function getDefinedStore<S extends object = any>(name: string): DefinedStoreWithGettersAndActions<S, any, any> | undefined;
+/**
+ * Get all defined store names.
+ */
+export declare function getDefinedStoreNames(): string[];
+/**
+ * Check if a store is defined.
+ */
+export declare function hasDefinedStore(name: string): boolean;
+/**
+ * Generate client-side runtime code for store imports.
+ * Uses the stx runtime to avoid exposing window.* to developers.
+ */
+export declare function generateStoreImportRuntime(): string;
+/**
+ * Transform import statements from @stores to runtime code.
+ *
+ * Transforms:
+ * ```js
+ * import { appStore, chatStore } from '@stores'
+ * ```
+ *
+ * Into:
+ * ```js
+ * const appStore = stx.useStore('appStore');
+ * const chatStore = stx.useStore('chatStore');
+ * ```
+ *
+ * The stx runtime is injected automatically and abstracts away window.* access.
+ */
+export declare function transformStoreImports(code: string): string;
+/**
+ * Generate store registration code for the client.
+ *
+ * @example
+ * ```js
+ * // In your stores file (e.g., stores/index.ts)
+ * import { defineStore, registerStoresClient } from 'stx'
+ *
+ * export const appStore = defineStore('app', { ... })
+ * export const chatStore = defineStore('chat', { ... })
+ *
+ * // Register for client-side @stores imports
+ * if (typeof window !== 'undefined') {
+ *   registerStoresClient({ appStore, chatStore })
+ * }
+ * ```
+ */
+export declare function registerStoresClient(stores: Record<string, object>): void;
+/** Store options */
+export declare interface StoreOptions<T> {
+  name?: string
+  persist?: PersistOptions
+  devtools?: boolean
+  middleware?: StoreMiddleware<T>[]
+  equals?: (a: T, b: T) => boolean
+}
+/** Persistence options */
+export declare interface PersistOptions {
+  storage?: 'local' | 'session' | 'memory'
+  key?: string
+  serialize?: (value: unknown) => string
+  deserialize?: (value: string) => unknown
+  paths?: string[]
+  debounce?: number
+}
+/** Store interface */
+export declare interface Store<T> {
+  get: () => T
+  set: (value: T | ((prev: T) => T)) => void
+  subscribe: (subscriber: Subscriber<T>) => Unsubscribe
+  update: (updater: Partial<T> | ((prev: T) => Partial<T>)) => void
+  reset: () => void
+  name?: string
+  destroy: () => void
+}
+/** Computed options */
+export declare interface ComputedOptions {
+  equals?: <T>(a: T, b: T) => boolean
+}
+/** Action definition */
+export declare interface ActionDefinition<T, P extends unknown[], R> {
+  name: string
+  handler: (store: Store<T>, ...params: P) => R
+}
+/** Global store state */
+export declare interface GlobalState {
+  stores: Map<string, Store<unknown>>
+  subscriptions: Map<string, Set<Subscriber<unknown>>>
+}
+/**
+ * Store definition options for defineStore
+ */
+export declare interface DefineStoreOptions<S, G extends Record<string, (state: S) => any>, A extends Record<string, (...args: any[]) => any>> {
+  state: S | (() => S)
+  getters?: G
+  actions?: A
+  persist?: PersistOptions | boolean
+  devtools?: boolean
+}
+/**
+ * Store instance returned by defineStore
+ */
+export declare interface DefinedStore<S, G extends Record<string, (state: S) => any>, A extends Record<string, (...args: any[]) => any>> {
+  $state: S
+  $subscribe: (callback: Subscriber<S>) => Unsubscribe
+  $reset: () => void
+  $patch: (partial: Partial<S> | ((state: S) => void)) => void
+  _store: Store<S>
+  $id: string
+}
+/** Subscription callback */
+// eslint-disable-next-line pickier/no-unused-vars
+export type Subscriber<T> = (value: T, previousValue: T | undefined) => void;
+/** Unsubscribe function */
+export type Unsubscribe = () => void;
+/** Store middleware */
+export type StoreMiddleware<T> = (
+  set: (value: T) => void,
+  get: () => T,
+  store: Store<T>
+) => (nextSet: (value: T) => void) => (value: T) => void;
+// Type helper for getters
+declare type StoreGetters<S, G extends Record<string, (state: S) => any>> = {
+  [K in keyof G]: ReturnType<G[K]>
+}
+// Type helper for actions
+declare type StoreActions<A extends Record<string, (...args: any[]) => any>> = {
+  [K in keyof A]: A[K]
+}
+// Full store type combining state, getters, and actions
+export type DefinedStoreWithGettersAndActions<S, G extends Record<string, (state: S) => any>, A extends Record<string, (...args: any[]) => any>,> = DefinedStore<S, G, A> & StoreGetters<S, G> & StoreActions<A>;