@biruframework/core 1.0.0

package/auth/index.js

@@ -0,0 +1,93 @@
+import { AppError } from '../base.js';
+import { createJsonStorage } from '../storage/index.js';
+
+export class AuthError extends AppError {
+  /**
+   * @param {string} message
+   * @param {{ cause?: unknown, meta?: Record<string, unknown> }=} options
+   */
+  constructor(message, options) {
+    super('AUTH_ERROR', message, options);
+    this.name = 'AuthError';
+  }
+}
+
+/**
+ * @typedef {{
+ *   accessToken: string,
+ *   refreshToken?: string,
+ *   expiresAt?: string,
+ *   user?: Record<string, unknown>,
+ * }} AuthSession
+ */
+
+/**
+ * @typedef {{ username: string, password: string }} LoginCredentials
+ */
+
+/**
+ * @typedef {{ login: string, logout?: string, me?: string }} AuthEndpoints
+ */
+
+/**
+ * @typedef {{
+ *   httpClient: { request?: Function, get?: Function, post: Function },
+ *   storage: { getItem: Function, setItem: Function, removeItem: Function, clear: Function },
+ *   endpoints: AuthEndpoints,
+ *   sessionStorageKey?: string,
+ * }} CreateAuthServiceOptions
+ */
+
+/**
+ * @param {CreateAuthServiceOptions} options
+ */
+export function createAuthService(options) {
+  const sessionKey = options.sessionStorageKey ?? 'auth.session';
+  const sessionStorage = createJsonStorage(options.storage, sessionKey);
+
+  /** @returns {Promise<AuthSession | null>} */
+  async function getSession() {
+    return await sessionStorage.get();
+  }
+
+  /** @param {AuthSession | null} session */
+  async function setSession(session) {
+    if (session == null) {
+      await sessionStorage.remove();
+      return;
+    }
+    await sessionStorage.set(session);
+  }
+
+  /** @param {LoginCredentials} credentials */
+  async function login(credentials) {
+    try {
+      const response = await options.httpClient.post(options.endpoints.login, {
+        body: credentials,
+      });
+      const session = response.data;
+      if (!session?.accessToken) throw new AuthError('Login response missing accessToken');
+      await setSession(session);
+      return session;
+    } catch (e) {
+      if (e instanceof AppError) throw e;
+      throw new AuthError('Login failed', { cause: e });
+    }
+  }
+
+  async function logout() {
+    try {
+      const currentSession = await getSession();
+      await setSession(null);
+      if (!options.endpoints.logout) return;
+      if (!currentSession?.accessToken) return;
+      await options.httpClient.post(options.endpoints.logout, {
+        headers: { Authorization: `Bearer ${currentSession.accessToken}` },
+      });
+    } catch (e) {
+      return;
+    }
+  }
+
+  return { getSession, setSession, login, logout };
+}

package/base.js

@@ -0,0 +1,78 @@
+/**
+ * @template T
+ * @typedef {Record<string, T>} Dictionary
+ */
+
+/** @typedef {null | undefined} Nil */
+
+/**
+ * @template T
+ * @typedef {{ ok: true, value: T }} Ok
+ */
+
+/**
+ * @template {Error} [E=Error]
+ * @typedef {{ ok: false, error: E }} Err
+ */
+
+/**
+ * @template T
+ * @template {Error} [E=Error]
+ * @typedef {Ok<T> | Err<E>} Result
+ */
+
+/**
+ * @template T
+ * @param {T} value
+ * @returns {Ok<T>}
+ */
+export function ok(value) {
+  return { ok: true, value };
+}
+
+/**
+ * @template {Error} E
+ * @param {E} error
+ * @returns {Err<E>}
+ */
+export function err(error) {
+  return { ok: false, error };
+}
+
+export class AppError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{ cause?: unknown, meta?: Dictionary<unknown> }=} options
+   */
+  constructor(code, message, options) {
+    super(message);
+    this.name = 'AppError';
+    this.code = code;
+    this.cause = options?.cause;
+    this.meta = options?.meta;
+  }
+}
+
+/**
+ * @typedef {{
+ *   debug: (message: string, meta?: Dictionary<unknown>) => void,
+ *   info: (message: string, meta?: Dictionary<unknown>) => void,
+ *   warn: (message: string, meta?: Dictionary<unknown>) => void,
+ *   error: (message: string, meta?: Dictionary<unknown>) => void,
+ * }} Logger
+ */
+
+/**
+ * @param {string=} prefix
+ * @returns {Logger}
+ */
+export function createConsoleLogger(prefix = 'app') {
+  const p = `[${prefix}]`;
+  return {
+    debug: (m, meta) => console.debug(p, m, meta ?? ''),
+    info: (m, meta) => console.info(p, m, meta ?? ''),
+    warn: (m, meta) => console.warn(p, m, meta ?? ''),
+    error: (m, meta) => console.error(p, m, meta ?? ''),
+  };
+}

package/index.js

@@ -0,0 +1,10 @@
+/**
+ * @biruframework/core - Otak template: logic platform-agnostic (auth, network, storage, state, routes)
+ * Gunakan untuk React Native maupun Web.
+ */
+export * from './base.js';
+export * from './network/index.js';
+export * from './storage/index.js';
+export * from './auth/index.js';
+export * from './state/index.js';
+export * from './routes/index.js';

package/network/errors/HttpError.js

@@ -0,0 +1,15 @@
+import { AppError } from '../../base.js';
+
+export class HttpError extends AppError {
+  /**
+   * @param {number} status
+   * @param {string} message
+   * @param {unknown} data
+   */
+  constructor(status, message, data) {
+    super('HTTP_ERROR', message, { meta: { status } });
+    this.name = 'HttpError';
+    this.status = status;
+    this.data = data;
+  }
+}

package/network/errors/NetworkError.js

@@ -0,0 +1,12 @@
+import { AppError } from '../../base.js';
+
+export class NetworkError extends AppError {
+  /**
+   * @param {string} message
+   * @param {{ cause?: unknown, meta?: Record<string, unknown> }=} options
+   */
+  constructor(message, options) {
+    super('NETWORK_ERROR', message, options);
+    this.name = 'NetworkError';
+  }
+}

package/network/http/createHttpClient.js

@@ -0,0 +1,114 @@
+import { AppError } from '../../base.js';
+import { HttpError } from '../errors/HttpError.js';
+import { NetworkError } from '../errors/NetworkError.js';
+
+/**
+ * @param {string} url
+ * @param {Record<string, string | number | boolean | null | undefined>=} query
+ */
+function buildUrl(url, query) {
+  if (!query) return url;
+  const u = new URL(url);
+  for (const [k, v] of Object.entries(query)) {
+    if (v === null || v === undefined) continue;
+    u.searchParams.set(k, String(v));
+  }
+  return u.toString();
+}
+
+/**
+ * @param {Response} res
+ * @returns {Promise<unknown>}
+ */
+async function readBody(res) {
+  const ct = res.headers.get('content-type') ?? '';
+  if (ct.includes('application/json')) return await res.json();
+  return await res.text();
+}
+
+/**
+ * @typedef {{
+ *   method: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE',
+ *   url: string,
+ *   headers?: Record<string, string>,
+ *   query?: Record<string, string | number | boolean | null | undefined>,
+ *   body?: unknown,
+ *   timeoutMs?: number,
+ * }} HttpRequest
+ */
+
+/**
+ * @template T
+ * @typedef {{ ok: boolean, status: number, headers: Headers, data: T, raw: Response }} HttpResponse
+ */
+
+/**
+ * @typedef {{
+ *   request: <T = unknown>(req: HttpRequest) => Promise<HttpResponse<T>>,
+ *   get: <T = unknown>(url: string, req?: Omit<HttpRequest, 'method' | 'url'>) => Promise<HttpResponse<T>>,
+ *   post: <T = unknown>(url: string, req?: Omit<HttpRequest, 'method' | 'url'>) => Promise<HttpResponse<T>>,
+ * }} HttpClient
+ */
+
+/**
+ * @typedef {{
+ *   defaultHeaders?: Record<string, string>,
+ *   fetchImpl?: typeof fetch,
+ * }} CreateHttpClientOptions
+ */
+
+/**
+ * @param {CreateHttpClientOptions=} options
+ * @returns {HttpClient}
+ */
+export function createHttpClient(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const defaultHeaders = options.defaultHeaders ?? {};
+
+  /**
+   * @template T
+   * @param {HttpRequest} req
+   * @returns {Promise<HttpResponse<T>>}
+   */
+  async function request(req) {
+    const controller = new AbortController();
+    const timeout = req.timeoutMs
+      ? setTimeout(() => controller.abort('timeout'), req.timeoutMs)
+      : undefined;
+
+    try {
+      const headers = {
+        Accept: 'application/json',
+        ...defaultHeaders,
+        ...(req.headers ?? {}),
+      };
+
+      const hasBody = req.body !== undefined;
+      const body =
+        hasBody && typeof req.body === 'string' ? req.body : hasBody ? JSON.stringify(req.body) : undefined;
+      if (hasBody && typeof req.body !== 'string') headers['Content-Type'] ??= 'application/json';
+
+      const res = await fetchImpl(buildUrl(req.url, req.query), {
+        method: req.method,
+        headers,
+        body,
+        signal: controller.signal,
+      });
+
+      const data = /** @type {any} */ (await readBody(res));
+      if (!res.ok) throw new HttpError(res.status, `Request failed with status ${res.status}`, data);
+      return { ok: true, status: res.status, headers: res.headers, data, raw: res };
+    } catch (e) {
+      if (e instanceof AppError) throw e;
+      throw new NetworkError('Network request failed', { cause: e });
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+  }
+
+  return {
+    request,
+    get: (url, req) => request({ ...(req ?? {}), method: 'GET', url }),
+    post: (url, req) => request({ ...(req ?? {}), method: 'POST', url }),
+  };
+}

package/network/index.js

@@ -0,0 +1,3 @@
+export * from './errors/NetworkError.js';
+export * from './errors/HttpError.js';
+export * from './http/createHttpClient.js';

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@biruframework/core",
+  "version": "1.0.0",
+  "description": "Template brain: auth, network, storage, state, routes (platform-agnostic)",
+  "main": "index.js",
+  "exports": { ".": "./index.js" },
+  "keywords": ["biruframework", "core", "auth", "network", "storage"],
+  "license": "ISC"
+}

package/routes/index.js

@@ -0,0 +1,38 @@
+/**
+ * @typedef {{
+ *   name: string,
+ *   path?: string,
+ *   meta?: Record<string, unknown>,
+ * }} RouteConfig
+ */
+
+/**
+ * @param {RouteConfig} config
+ * @returns {RouteConfig}
+ */
+export function defineRoute(config) {
+  return config;
+}
+
+/**
+ * @template {Record<string, RouteConfig>} T
+ * @param {T} routes
+ * @returns {T}
+ */
+export function defineRoutes(routes) {
+  return routes;
+}
+
+/**
+ * @param {string} template
+ * @param {Record<string, string | number | boolean | null | undefined>} params
+ * @returns {string}
+ */
+export function buildPath(template, params) {
+  let path = template;
+  for (const [key, value] of Object.entries(params)) {
+    const safeValue = value == null ? '' : encodeURIComponent(String(value));
+    path = path.replace(new RegExp(`:${key}\\b`, 'g'), safeValue);
+  }
+  return path;
+}

package/state/index.js

@@ -0,0 +1,90 @@
+import { AppError } from '../base.js';
+
+export class StateError extends AppError {
+  /**
+   * @param {string} message
+   * @param {{ cause?: unknown, meta?: Record<string, unknown> }=} options
+   */
+  constructor(message, options) {
+    super('STATE_ERROR', message, options);
+    this.name = 'StateError';
+  }
+}
+
+/** @typedef {() => void} Unsubscribe */
+
+/**
+ * @template TState
+ * @typedef {(nextState: TState, prevState: TState) => void} StoreListener
+ */
+
+/**
+ * @template TState
+ * @typedef {{
+ *   getState: () => TState,
+ *   setState: (nextState: TState) => void,
+ *   update: (updater: (current: TState) => TState) => void,
+ *   subscribe: (listener: StoreListener<TState>) => Unsubscribe,
+ * }} Store
+ */
+
+/**
+ * @template TState
+ * @param {TState} initialState
+ * @returns {Store<TState>}
+ */
+export function createStore(initialState) {
+  let state = initialState;
+  const listeners = new Set();
+
+  /**
+   * @param {TState} nextState
+   * @param {TState} prevState
+   */
+  function notify(nextState, prevState) {
+    for (const listener of listeners) listener(nextState, prevState);
+  }
+
+  return {
+    getState: () => state,
+    setState: (nextState) => {
+      const prevState = state;
+      state = nextState;
+      notify(state, prevState);
+    },
+    update: (updater) => {
+      const prevState = state;
+      state = updater(state);
+      notify(state, prevState);
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+/**
+ * @template TValue
+ * @typedef {{
+ *   get: () => TValue,
+ *   set: (value: TValue) => void,
+ *   update: (updater: (current: TValue) => TValue) => void,
+ *   subscribe: (listener: StoreListener<TValue>) => Unsubscribe,
+ * }} Atom
+ */
+
+/**
+ * @template TValue
+ * @param {TValue} initialValue
+ * @returns {Atom<TValue>}
+ */
+export function createAtom(initialValue) {
+  const store = createStore(initialValue);
+  return {
+    get: store.getState,
+    set: store.setState,
+    update: store.update,
+    subscribe: store.subscribe,
+  };
+}

package/storage/index.js

@@ -0,0 +1,90 @@
+import { AppError } from '../base.js';
+
+export class StorageError extends AppError {
+  /**
+   * @param {string} message
+   * @param {{ cause?: unknown }=} options
+   */
+  constructor(message, options) {
+    super('STORAGE_ERROR', message, { cause: options?.cause });
+    this.name = 'StorageError';
+  }
+}
+
+/**
+ * @typedef {{
+ *   getItem: (key: string) => Promise<string | null>,
+ *   setItem: (key: string, value: string) => Promise<void>,
+ *   removeItem: (key: string) => Promise<void>,
+ *   clear: () => Promise<void>,
+ * }} KeyValueStorage
+ */
+
+export class MemoryStorage {
+  map = new Map();
+
+  /** @param {string} key */
+  async getItem(key) {
+    return this.map.has(key) ? (this.map.get(key) ?? null) : null;
+  }
+
+  /**
+   * @param {string} key
+   * @param {string} value
+   */
+  async setItem(key, value) {
+    this.map.set(key, value);
+  }
+
+  /** @param {string} key */
+  async removeItem(key) {
+    this.map.delete(key);
+  }
+
+  async clear() {
+    this.map.clear();
+  }
+}
+
+/**
+ * @template T
+ * @typedef {{
+ *   get: () => Promise<T | null>,
+ *   set: (value: T) => Promise<void>,
+ *   remove: () => Promise<void>,
+ * }} JsonStorage
+ */
+
+/**
+ * @template T
+ * @param {KeyValueStorage} storage
+ * @param {string} key
+ * @returns {JsonStorage<T>}
+ */
+export function createJsonStorage(storage, key) {
+  return {
+    get: async () => {
+      try {
+        const raw = await storage.getItem(key);
+        if (raw == null) return null;
+        return /** @type {T} */ (JSON.parse(raw));
+      } catch (e) {
+        throw new StorageError(`Failed to read key "${key}"`, { cause: e });
+      }
+    },
+    set: async (value) => {
+      try {
+        await storage.setItem(key, JSON.stringify(value));
+      } catch (e) {
+        throw new StorageError(`Failed to write key "${key}"`, { cause: e });
+      }
+    },
+    remove: async () => {
+      try {
+        await storage.removeItem(key);
+      } catch (e) {
+        throw new StorageError(`Failed to remove key "${key}"`, { cause: e });
+      }
+    },
+  };
+}