@tiny-server/core 0.0.0

package/src/app/features/router/context.ts

@@ -0,0 +1,7 @@
+import { createContext } from 'react-router';
+import type { AppInstance } from '../../types';
+
+/**
+ * A router context which grants access to current {@link AppInstance}.
+ */
+export const appContext = createContext<AppInstance>();

package/src/app/features/router/index.ts

@@ -0,0 +1,3 @@
+export * from './AppRouter';
+export * from './context';
+export * from './middlewares';

package/src/app/features/router/middlewares.ts

@@ -0,0 +1,76 @@
+import { data, redirect, type MiddlewareFunction } from 'react-router';
+import { appContext } from './context';
+import { readSessionStateQuery, type Permission } from '../../../api';
+
+export interface RequireSessionMiddlewareOptions {
+  /**
+   * The URL to which an anonymous user should be redirected to.
+   * @default '/'
+   */
+  redirectUrl?: string;
+  /**
+   * A set of permissions which are required to access the route.
+   */
+  permissions?: Array<Permission>;
+  /**
+   * A custom callback which allows custom handling of unauthorized access errors, i.e., situations
+   * where no active session exists.
+   * If not provided, the middleware will redirect to {@link redirectUrl}.
+   */
+  onUnauthorized?: () => void | Promise<void>;
+  /**
+   * A custom callback which allows custom handling of forbidden access errors, i.e., situations
+   * where the user session does not have the required permissions.
+   * If not provided, the middleware will throw a `403` data error.
+   */
+  onForbidden?: () => void | Promise<void>;
+}
+
+/**
+ * Creates a router middleware function which ensures that an active user session exists.
+ * If no session exists, the user is redirected to {@link RequireSessionMiddlewareOptions#redirectUrl}.
+ */
+export function requireSession({
+  redirectUrl = '/',
+  permissions = [],
+  onUnauthorized,
+  onForbidden,
+}: RequireSessionMiddlewareOptions = {}): MiddlewareFunction {
+  return async ({ context }) => {
+    const { queryClient } = context.get(appContext);
+    const { session } = await queryClient.ensureQueryData(readSessionStateQuery());
+
+    if (!session) {
+      await onUnauthorized?.();
+      throw redirect(redirectUrl);
+    }
+
+    if (!permissions.every((permission) => session.permissions.includes(permission))) {
+      await onForbidden?.();
+      throw data({ message: `Permission(s) '${permissions.join(', ')}' required` }, 403);
+    }
+  };
+}
+
+export interface RequireAnonymousMiddlewareOptions {
+  /**
+   * The URL to which a logged in user should be redirected to.
+   * @default '/'
+   */
+  redirectUrl?: string;
+}
+
+/**
+ * Creates a router middleware function which ensures that no user session exists.
+ * If a session exists, the user is redirected to {@link RequireAnonymousMiddlewareOptions#redirectUrl}.
+ */
+export function requireAnonymous({ redirectUrl = '/' }: RequireAnonymousMiddlewareOptions = {}): MiddlewareFunction {
+  return async ({ context }) => {
+    const { queryClient } = context.get(appContext);
+    const { hasSession } = await queryClient.ensureQueryData(readSessionStateQuery());
+
+    if (hasSession) {
+      throw redirect(redirectUrl);
+    }
+  };
+}

package/src/app/index.ts

@@ -0,0 +1,6 @@
+export * from './features';
+
+export * from './App';
+export { useApp } from './context';
+export * from './create';
+export * from './types';

package/src/app/types.ts

@@ -0,0 +1,82 @@
+import type { RouteObject } from 'react-router';
+import type { AnyExtensionRegistration } from './features/extensions';
+import type { AnyMenuItemRegistration } from './features/menu';
+import type { AnyModalRegistration } from './features/modals';
+import type { ComponentType, PropsWithChildren } from 'react';
+
+/**
+ * Represents an instance of a configured application.
+ * {@link AppInstance} objects provide the app's central orchestration API.
+ */
+export interface AppInstance {
+  /**
+   * The set of modules which make up this application instance.
+   */
+  modules: Array<Module>;
+  /**
+   * A set of application specific components.
+   */
+  components: AppComponents;
+}
+
+/**
+ * Represents a set of configurable components which can be declared by modules
+ * and used by any component that has access to the application instance.
+ *
+ * This interface can be extended by modules via declaration merging.
+ *
+ * ```ts
+ * declare module '@tiny-server/core' {
+ *   export interface AppComponents {
+ *     MyComponent: ComponentType<MyComponentProps>;
+ *   }
+ * }
+ * ```
+ */
+export interface AppComponents {}
+
+/**
+ * An initializer function which can be registered as part of a module configuration.
+ *
+ * App initializers are called during app creation, receiving an {@link AppInstance}.
+ * They can perform any necessary setup or (re-)configuration of the app instance.
+ *
+ * App initializers *may* mutate the given app instance.
+ */
+export type AppInitializer = (app: AppInstance) => AppInstance | void;
+
+/**
+ * Initialization values for {@link Module} objects.
+ */
+export type ModuleInit = Partial<Module>;
+
+/**
+ * Represents an application module.
+ */
+export interface Module {
+  /**
+   * Module-provided {@link AppInitializer} functions.
+   */
+  appInitializers: Array<AppInitializer>;
+  /**
+   * Module-provided provider components.
+   * These are rendered at the very top of the app's component tree.
+   */
+  providers: Array<ComponentType<PropsWithChildren>>;
+  /**
+   * Module-provided routes.
+   */
+  routes: Array<RouteObject>;
+  /**
+   * Module-provided extensions.
+   */
+  extensions: Array<AnyExtensionRegistration>;
+  /**
+   * Module-provided menu items.
+   */
+  menuItems: Array<AnyMenuItemRegistration>;
+  /**
+   * Module-provided modals.
+   */
+  modals: Array<AnyModalRegistration>;
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,34 @@
+import { Component, type PropsWithChildren, type ReactNode } from 'react';
+
+interface State {
+  hasError: boolean;
+}
+
+export interface ErrorBoundaryProps extends PropsWithChildren {
+  /**
+   * The fallback to render when an error is caught.
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * A generic error boundary component which renders a fallback when an error is caught.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback;
+    }
+
+    return this.props.children;
+  }
+}

package/src/components/WithPermissions.tsx

@@ -0,0 +1,59 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { Permission } from '../api';
+import { usePermissions } from '../utils';
+
+export interface WithPermissionsProps {
+  /**
+   * The required permissions.
+   * @default []
+   */
+  permissions?: Array<Permission>;
+  /**
+   * The operator to use for checking permissions.
+   * @default 'and'
+   */
+  operator?: 'and' | 'or';
+  /**
+   * The content to render when the user has the required permissions.
+   */
+  children?: ReactNode;
+  /**
+   * The content to render when the user is lacking the required permissions.
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * Renders content depending on whether the users has one or more given permissions.
+ */
+export function WithPermissions({ permissions = [], operator = 'and', children, fallback }: WithPermissionsProps) {
+  const userPermissions = usePermissions();
+  const hasPermissions =
+    operator === 'and'
+      ? permissions.every((permission) => userPermissions.includes(permission))
+      : permissions.some((permission) => userPermissions.includes(permission));
+
+  if (!hasPermissions) {
+    return <>{fallback}</>;
+  }
+
+  return <>{children}</>;
+}
+
+/**
+ * Wraps the given component in a {@link WithPermissions} component.
+ */
+export function withPermissions<T extends object>(
+  withPermissionProps: Omit<WithPermissionsProps, 'children'>,
+  WrappedComponent: ComponentType<T>,
+): ComponentType<T> {
+  const hoc = function WithPermissionHoc(props: T) {
+    return (
+      <WithPermissions {...withPermissionProps}>
+        <WrappedComponent {...props} />
+      </WithPermissions>
+    );
+  };
+
+  return hoc;
+}

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export * from './ErrorBoundary';
+export * from './WithPermissions';

package/src/fetch.ts

@@ -0,0 +1,185 @@
+import { isProblemDetails, type ProblemDetails } from './api';
+
+/**
+ * Arguments for making an HTTP request using {@link appFetch}.
+ */
+export interface AppFetchArgs<TResult = void> extends Omit<RequestInit, 'body'> {
+  /**
+   * The base URL to be used for the request.
+   * @default window.location.origin
+   */
+  baseUrl?: string;
+  /**
+   * The request URL.
+   */
+  url: string;
+  /**
+   * The body of the request.
+   * This body is, by default, automatically serialized as JSON **unless** the `Content-Type` header
+   * is set to a value other than `application/json`.
+   */
+  body?: BodyInit | object;
+  /**
+   * Additional query parameters to be appended to the URL.
+   * If set, these overwrite existing query parameters in {@link url} with the same name.
+   */
+  params?: AppFetchQueryParams;
+  /**
+   * Defines the handler which should be used to parse the response.
+   * @default 'json'
+   */
+  responseHandler?: DefaultResponseHandler | AppFetchResponseHandler<TResult>;
+  /**
+   * Defines the validators which should be used to validate the response.
+   * @default ['statusOk']
+   */
+  responseValidators?: Array<DefaultResponseValidator | AppFetchResponseValidator<TResult>>;
+}
+
+/**
+ * Supported query param types.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AppFetchQueryParams = Record<string, any>;
+
+/**
+ * Represents a function which handles/processes a {@link Response} object.
+ * These handlers are supposed
+ */
+export type AppFetchResponseHandler<TResult = void> = (response: Response) => Promise<TResult>;
+
+/**
+ * Represents a function which validates that a response produced by {@link appFetch} is valid.
+ */
+export type AppFetchResponseValidator<TResult = void> = (response: Response, result: TResult) => Promise<void>;
+
+const defaultResponseHandlers = {
+  json: async (response) => {
+    const contentType = response.headers.get('content-type');
+    if (contentType && !/application\/(.+\+)?json/.test(contentType)) {
+      throw new Error(`JSON response handler received invalid content type "${contentType}".`);
+    }
+
+    const text = await response.text();
+    try {
+      return text.length ? JSON.parse(text) : null;
+    } catch {
+      throw new Error('JSON response handler failed to parse JSON response.');
+    }
+  },
+} satisfies Record<string, AppFetchResponseHandler>;
+
+const defaultResponseValidators = {
+  statusOk: async (response: Response, result: unknown) => {
+    if (!response.ok) {
+      if (isProblemDetails(result)) {
+        throw new ProblemDetailsError(response, result);
+      }
+
+      throw new AppFetchError(response, `Request failed with status code ${response.status}.`);
+    }
+  },
+} satisfies Record<string, AppFetchResponseValidator>;
+
+export type DefaultResponseHandler = keyof typeof defaultResponseHandlers;
+export type DefaultResponseValidator = keyof typeof defaultResponseValidators;
+
+/**
+ * A function similar to {@link fetch}, but tailored for the application's conventional backend API.
+ * {@link appFetch} implements automatic response (de-serialization) and validation.
+ * By default, {@link appFetch} assumes that requests and responses are based on JSON and that
+ * any non-2xx status code represents an error.
+ * These defaults can be overwritten via {@link args}.
+ * @param args The arguments for the fetch request. This can be a string representing the URL if no additional options are required.
+ */
+export async function appFetch<TResult = void>(args: string | AppFetchArgs<TResult>): Promise<TResult> {
+  args = typeof args === 'string' ? { url: args } : args;
+  const {
+    baseUrl = window.location.origin,
+    url,
+    body,
+    params = {},
+    responseHandler = 'json',
+    responseValidators = ['statusOk'],
+    ...fetchInit
+  } = args;
+
+  const handleResponse =
+    typeof responseHandler === 'string' ? defaultResponseHandlers[responseHandler] : responseHandler;
+
+  const validateResponses = async (response: Response, result: TResult) => {
+    for (const validator of responseValidators) {
+      const validate = typeof validator === 'string' ? defaultResponseValidators[validator] : validator;
+      await validate(response, result);
+    }
+  };
+
+  const requestUrl = buildUrl(url, baseUrl, params);
+  const requestHeaders = new Headers(fetchInit.headers);
+  let requestBody: BodyInit | undefined;
+
+  if (
+    !(body instanceof FormData) &&
+    (!requestHeaders.has('Content-Type') || requestHeaders.get('Content-Type')?.includes('application/json'))
+  ) {
+    requestHeaders.set('Content-Type', 'application/json');
+    requestBody = JSON.stringify(body);
+  } else {
+    requestBody = body as BodyInit;
+  }
+
+  const requestInit: RequestInit = {
+    ...fetchInit,
+    headers: requestHeaders,
+    body: requestBody,
+  };
+
+  const response = await fetch(requestUrl, requestInit);
+  const result = await handleResponse(response);
+  await validateResponses(response, result);
+  return result;
+}
+
+function buildUrl(requestUrl: string, baseUrl: string, params: AppFetchQueryParams): URL {
+  const url = new URL(requestUrl, baseUrl);
+  const searchParams = url.searchParams;
+
+  for (const [key, value] of Object.entries(params)) {
+    const paramValues = Array.isArray(value) ? value : [value];
+
+    for (const paramValue of paramValues) {
+      if (paramValue !== undefined && paramValue !== null) {
+        searchParams.append(key, String(paramValue));
+      }
+    }
+  }
+
+  return url;
+}
+
+/**
+ * An error thrown by {@link appFetch} when a default validation fails.
+ */
+export class AppFetchError extends Error {
+  /**
+   * The received fetch response.
+   */
+  readonly response: Response;
+
+  constructor(response: Response, message?: string | null) {
+    super(message ?? 'An error occurred during a fetch request.');
+    this.response = response;
+  }
+}
+
+/**
+ * An error thrown by {@link appFetch} when the response contains a problem details object.
+ */
+export class ProblemDetailsError extends AppFetchError {
+  readonly problem: Readonly<ProblemDetails>;
+
+  constructor(response: Response, problem: ProblemDetails) {
+    super(response, problem.title);
+    this.problem = problem;
+  }
+}

package/src/i18n/InitI18n.tsx

@@ -0,0 +1,24 @@
+import { type PropsWithChildren, useEffect } from 'react';
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import type { InitOptions } from 'i18next';
+
+export interface InitI18nProps extends PropsWithChildren {
+  options?: InitOptions<unknown>;
+}
+
+const defaultOptions: InitOptions = {
+  lng: 'en',
+  fallbackLng: 'en',
+  interpolation: {
+    escapeValue: false,
+  },
+};
+
+export function InitI18n({ options = defaultOptions, children }: InitI18nProps) {
+  useEffect(() => {
+    i18n.use(initReactI18next).init(options);
+  }, [options]);
+
+  return children;
+}

package/src/i18n/defineLocales.ts

@@ -0,0 +1,59 @@
+import { useTranslation } from 'react-i18next';
+import i18next from 'i18next';
+
+type KeyPrefixOrFn = string | ((...args: Array<any>) => any);
+
+function makeKeyPrefix(keyPrefixOrFn: KeyPrefixOrFn | Array<KeyPrefixOrFn>) {
+  const stringify = (prefixOrFn: KeyPrefixOrFn) => (typeof prefixOrFn === 'string' ? prefixOrFn : prefixOrFn.name);
+
+  if (Array.isArray(keyPrefixOrFn)) {
+    // In the case of an array, we convert each array entry to the string representation.
+    // In addition, we add the current element index to the prefix.
+    // Why?
+    // Because i18n has issues if a parent prefix is used as part of the path. For example:
+    // Registration 1: parent
+    // Registration 2: parent.child
+    //
+    // Translations for parent.child will not be found. Using a different path for nested translations
+    // solves this.
+    // Applied to the example:
+    // Registration 1: parent
+    // Registration 2: parent-0.child
+    return keyPrefixOrFn.map((x, i) => stringify(x) + `-${i}`).join('.');
+  } else {
+    return stringify(keyPrefixOrFn);
+  }
+}
+
+/**
+ * Registers a translation resource bundle and creates a `useT` hook that returns a translation
+ * function which translates the registered keys.
+ * @param keyPrefixOrFn The key prefix or function that the translations are registered for.
+ * @param translations The set of translations to register, keyed by the language.
+ * @returns A `useT` hook that returns a {@link TFunction} that returns the registered translations.
+ */
+export function defineLocales<T extends Record<string, Record<string, unknown>>>(
+  keyPrefixOrFn: KeyPrefixOrFn | Array<KeyPrefixOrFn>,
+  translations: T,
+) {
+  const keyPrefix = makeKeyPrefix(keyPrefixOrFn);
+
+  const registerResourceBundle = () => {
+    for (const [language, resources] of Object.entries(translations)) {
+      i18next?.addResourceBundle(language, 'translation', { [keyPrefix]: resources }, true, true);
+    }
+
+    console.info(`Registered translations for key "${keyPrefix}".`);
+  };
+
+  if (i18next.isInitialized) {
+    registerResourceBundle();
+  } else {
+    i18next.on('initialized', registerResourceBundle);
+  }
+
+  return function useT() {
+    const { t } = useTranslation(undefined, { keyPrefix });
+    return t;
+  };
+}

package/src/i18n/index.ts

@@ -0,0 +1,3 @@
+export * from './defineLocales';
+export * from './InitI18n';
+export * from './useGlobalT';

package/src/i18n/useGlobalT.ts

@@ -0,0 +1,13 @@
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Returns a non-scoped translation function.
+ * To be used for accessing global translations.
+ * If possible, use {@link defineLocales} instead.
+ * @param keyPrefix An optional key prefix.
+ */
+
+export function useGlobalT(keyPrefix?: string) {
+  const { t } = useTranslation(undefined, { keyPrefix });
+  return t;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './api';
+export * from './app';
+export * from './components';
+export * from './utils';
+
+export * from './fetch';
+export * from './i18n/defineLocales';
+export * from './module';

package/src/module.tsx

@@ -0,0 +1,27 @@
+import type { InitOptions } from 'i18next';
+import {
+  AppQueryClientProvider,
+  createModule,
+  layoutInitializer,
+  menuInitializer,
+  modalsInitializer,
+  queryInitializer,
+} from './app';
+import { MantineProvider, type MantineProviderProps } from '@mantine/core';
+import { InitI18n } from './i18n';
+
+export interface CoreModuleOptions {
+  i18n?: InitOptions<unknown>;
+  mantineProviderProps?: MantineProviderProps;
+}
+
+export function createCoreModule(options: CoreModuleOptions = {}) {
+  return createModule({
+    appInitializers: [layoutInitializer, menuInitializer, modalsInitializer, queryInitializer],
+    providers: [
+      (props) => <AppQueryClientProvider {...props} />,
+      (props) => <MantineProvider {...options.mantineProviderProps} {...props} />,
+      (props) => <InitI18n options={options.i18n} {...props} />,
+    ],
+  });
+}

package/src/utils/dates.ts

@@ -0,0 +1,34 @@
+export function formatDate(date?: null | string | number | Date) {
+  return format(date, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  });
+}
+
+export function formatTime(date?: null | string | number | Date) {
+  return format(date, {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+}
+
+export function formatDateTime(date?: null | string | number | Date) {
+  return format(date, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+}
+
+function format(date: undefined | null | string | number | Date, options: Intl.DateTimeFormatOptions) {
+  if (date === undefined || date === null) {
+    return undefined;
+  }
+
+  return new Date(date).toLocaleString(undefined, options);
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './dates';
+export * from './usePagination';
+export * from './useSearch';
+export * from './useSession';