@tiny-server/core 0.0.0

package/src/api/apiResults.ts

@@ -0,0 +1,50 @@
+/**
+ * Wraps the result of an API endpoint and enriches that result with additional metadata.
+ */
+export interface ApiResult<T> {
+  /**
+   * The data returned by the API.
+   */
+  data: T;
+  /**
+   * The time when the API result was generated.
+   */
+  timestamp: string;
+}
+
+/**
+ * A specialized {@link ApiResult} for lists of data.
+ */
+export interface ListApiResult<T> extends ApiResult<Array<T>> {
+  /**
+   * The total number of items returned.
+   */
+  count: number;
+}
+
+export interface PaginationApiResult<T> extends ListApiResult<T> {
+  /**
+   * The returned page.
+   */
+  page: number;
+  /**
+   * The number of items per page.
+   */
+  pageSize: number;
+  /**
+   * The total number of items across all pages.
+   */
+  totalItems: number;
+  /**
+   * The total number of pages available.
+   */
+  totalPages: number;
+  /**
+   * Whether a previous page exists.
+   */
+  hasPreviousPage: boolean;
+  /**
+   * Whether a next page exists.
+   */
+  hasNextPage: boolean;
+}

package/src/api/entity.ts

@@ -0,0 +1,29 @@
+/**
+ * Represents a generic entity.
+ */
+export interface EntityRead<TId extends string = string> {
+  /**
+   * The entity's ID.
+   */
+  id: TId;
+  /**
+   * The date and time when the entity was created.
+   */
+  createdOn: string;
+  /**
+   * The date and time when the entity was last updated.
+   */
+  updatedOn: string;
+}
+
+/**
+ * Represents data for creating an entity.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface EntityCreate {}
+
+/**
+ * Represents data for updating an entity.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface EntityUpdate {}

package/src/api/index.ts

@@ -0,0 +1,8 @@
+export * from './apiResults';
+export * from './entity';
+export * from './paginationOptions';
+export * from './permissions';
+export * from './problemDetails';
+export * from './session';
+export * from './sortOptions';
+export * from './status';

package/src/api/paginationOptions.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for querying pagination APIs.
+ */
+export interface PaginationOptions {
+  /**
+   * The requested page number.
+   */
+  page?: number | null;
+  /**
+   * The requested page size.
+   */
+  pageSize?: number | null;
+}

package/src/api/permissions.ts

@@ -0,0 +1,63 @@
+import { queryOptions } from '@tanstack/react-query';
+import { appFetch } from '../fetch';
+import type { ListApiResult } from './apiResults';
+
+/**
+ * An interface mapping all known backend permissions to an arbitrary value.
+ * {@link Permissions} is derived from this interface`s key.
+ *
+ * You can extend known {@link Permission}s by declaring a module augmentation for this interface.
+ *
+ * @example
+ * ```ts
+ * declare module "@tiny-server/core" {
+ *   interface PermissionsMap {
+ *    ["my.permission"]: "";
+ *   }
+ * }
+ *
+ * // Results in:
+ * const permission: Permission = "my.permission"; // ✅ Valid
+ * ```
+ */
+export interface PermissionsMap {
+  ['read.all']: '';
+  ['write.all']: '';
+}
+
+/**
+ * Declares all known backend permissions.
+ */
+export type Permission = keyof PermissionsMap;
+
+/**
+ * Represents a permission with its hierarchy information.
+ */
+export interface PermissionRead {
+  /**
+   * The permission`s name.
+   */
+  name: Permission;
+  /**
+   * The permission`s direct parent names.
+   */
+  parents: Array<Permission>;
+  /**
+   * All parent names, including parents of parents, and so on.
+   */
+  allParents: Array<Permission>;
+}
+
+/** `GET /api/v1/permissions` */
+export function readPermissions(): Promise<ListApiResult<PermissionRead>> {
+  return appFetch<ListApiResult<PermissionRead>>('/api/v1/permissions');
+}
+
+/** {@link readPermissions} */
+export function readPermissionsQuery() {
+  return queryOptions({
+    queryKey: ['permissions'],
+    queryFn: () => readPermissions(),
+    staleTime: Infinity,
+  });
+}

package/src/api/problemDetails.ts

@@ -0,0 +1,19 @@
+/**
+ *  A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
+ */
+export interface ProblemDetails {
+  type?: string | null;
+  title?: string | null;
+  status?: number | null;
+  detail?: string | null;
+  instance?: string | null;
+  errors?: Record<string, Array<string>>;
+  [key: string]: unknown;
+}
+
+/**
+ * Returns whether the given object is a {@link ProblemDetails} object.
+ */
+export function isProblemDetails(obj: unknown): obj is ProblemDetails {
+  return !!obj && typeof obj === 'object';
+}

package/src/api/session.ts

@@ -0,0 +1,51 @@
+import { queryOptions } from '@tanstack/react-query';
+import { appFetch, AppFetchError } from '../fetch';
+import type { ApiResult } from './apiResults';
+import type { Permission } from './permissions';
+
+/**
+ * Provides information about the current user session.
+ */
+export interface SessionRead {
+  /**
+   * The identifier of the user associated with the current session.
+   */
+  userId: string;
+  /**
+   * All permissions associated with the session's user.
+   */
+  permissions: Array<Permission>;
+}
+
+/**
+ * Represents the current session state, i.e., whether the user has an active session or not.
+ */
+export type SessionState = { hasSession: false; session: undefined } | { hasSession: true; session: SessionRead };
+
+/**
+ * Calls `GET /api/v1/auth/session` and extracts the current {@link SessionState} from the response.
+ * Throws for any errors other than `401 Unauthorized`.
+ */
+export async function readSessionState(): Promise<SessionState> {
+  try {
+    const { data } = await appFetch<ApiResult<SessionRead>>('/api/v1/auth/session');
+    return { hasSession: true, session: data };
+  } catch (e) {
+    if (e instanceof AppFetchError && e.response.status === 401) {
+      return { hasSession: false, session: undefined };
+    }
+
+    // We want error/retry semantics for unknown/unexpected errors.
+    throw e;
+  }
+}
+
+/** {@link readSessionState} */
+export function readSessionStateQuery() {
+  return queryOptions({
+    queryKey: ['session'],
+    queryFn: () => readSessionState(),
+    staleTime: Infinity,
+    gcTime: Infinity,
+  });
+}

package/src/api/sortOptions.ts

@@ -0,0 +1,18 @@
+/**
+ * Defines the possible sort directions for sorting operations.
+ */
+export type SortDirection = 'Ascending' | 'Descending';
+
+/**
+ * Defines options for sorting items.
+ */
+export interface SortOptions<TKey extends string> {
+  /**
+   * The key to sort by.
+   */
+  sortBy?: TKey | null;
+  /**
+   * The direction of the sort operation.
+   */
+  sortDirection?: SortDirection | null;
+}

package/src/api/status.ts

@@ -0,0 +1,34 @@
+import { appFetch } from '../fetch';
+import type { Permission } from './permissions';
+import { queryOptions } from '@tanstack/react-query';
+import type { ApiResult } from './apiResults';
+
+export type StatusVersion = `${number}.${number}.${number}`;
+
+/**
+ * Provides status information about the service.
+ */
+export interface StatusRead {
+  /**
+   * The service version.
+   */
+  version: StatusVersion;
+  /**
+   * All known permissions.
+   */
+  permissions: Array<Permission>;
+}
+
+/** `GET api/v1/status` */
+export function readStatus(): Promise<ApiResult<StatusRead>> {
+  return appFetch<ApiResult<StatusRead>>('/api/v1/status');
+}
+
+/** {@link readStatus} */
+export function readStatusQuery() {
+  return queryOptions({
+    queryKey: ['status'],
+    queryFn: () => readStatus(),
+    staleTime: Infinity,
+  });
+}

package/src/app/App.tsx

@@ -0,0 +1,33 @@
+import { AppRouter } from './features/router';
+import { appContext } from './context';
+import type { AppInstance } from './types';
+import { useCallback, type FunctionComponent, type PropsWithChildren } from 'react';
+
+export interface AppProps extends PropsWithChildren {
+  /**
+   * The application instance to be rendered.
+   */
+  app: AppInstance;
+}
+
+/**
+ * The main application component, rendering an application and its configured modules.
+ */
+export function App({ app, children }: AppProps) {
+  const AppProviders = useCallback<FunctionComponent<PropsWithChildren>>(
+    ({ children }) => {
+      const providers = app.modules.flatMap((m) => m.providers);
+      return providers.reduceRight((tree, Provider) => <Provider>{tree}</Provider>, children);
+    },
+    [app.modules],
+  );
+
+  return (
+    <appContext.Provider value={app}>
+      <AppProviders>
+        <AppRouter />
+        {children}
+      </AppProviders>
+    </appContext.Provider>
+  );
+}

package/src/app/context.ts

@@ -0,0 +1,17 @@
+import { createContext, useContext } from 'react';
+import type { AppInstance } from './types';
+
+export const appContext = createContext<AppInstance>(null!);
+
+/**
+ * Retrieves the configured {@link AppInstance}.
+ */
+export function useApp(): AppInstance {
+  const app = useContext(appContext);
+
+  if (!app) {
+    throw new Error('App context had no configured value. Was the hook called outside of an <App> component?');
+  }
+
+  return app;
+}

package/src/app/create.ts

@@ -0,0 +1,34 @@
+import type { AppInstance, Module, ModuleInit } from './types';
+
+/**
+ * Creates an {@link AppInstance} based on the provided configuration.
+ * {@link AppInstance} objects provide the app's central orchestration API.
+ * @param modules The modules making up the application.
+ */
+export function createApp(modules: Array<Module>): AppInstance {
+  let app: AppInstance = {
+    modules,
+    components: {},
+  } as AppInstance;
+
+  for (const initializer of modules.flatMap((m) => m.appInitializers)) {
+    app = initializer(app) ?? app;
+  }
+
+  return app;
+}
+
+/**
+ * Creates a fully configured {@link Module} based on the given {@link ModuleInit}.
+ * @param moduleInit The configuration with which to initialize the module.
+ */
+export function createModule(moduleInit: ModuleInit): Module {
+  return {
+    appInitializers: moduleInit.appInitializers ?? [],
+    routes: moduleInit.routes ?? [],
+    extensions: moduleInit.extensions ?? [],
+    menuItems: moduleInit.menuItems ?? [],
+    modals: moduleInit.modals ?? [],
+    providers: moduleInit.providers ?? [],
+  };
+}

package/src/app/features/extensions/Extension.tsx

@@ -0,0 +1,69 @@
+import { type ReactNode, useMemo, Suspense, type ComponentType } from 'react';
+import { ErrorBoundary } from '../../../components';
+import type { ExtensionComponentProps, ExtensionName, ExtensionParams } from './types';
+import { useApp } from '../../context';
+
+export interface ExtensionProps<TName extends ExtensionName> {
+  /**
+   * The name of the extension to render.
+   */
+  name: TName;
+  /**
+   * The parameters to be forwarded to the extension component.
+   */
+  params: ExtensionParams<TName>;
+  /**
+   * An optional fallback to render if:
+   * - there is no extension with the given name.
+   * - no {@link loadingFallback} is provided and the extension is loading.
+   * - no {@link errorFallback} is provided and the extension errored.
+   */
+  fallback?: ReactNode;
+  /**
+   * An optional fallback to render while the extension is being lazy-loaded.
+   */
+  loadingFallback?: ReactNode;
+  /**
+   * An optional fallback to render if an error is caught while rendering the extension.
+   */
+  errorFallback?: ReactNode;
+}
+
+/**
+ * Renders registered extension componentsmatching the given name.
+ * If no such extension components are known, renders a fallback.
+ */
+export function Extension<TName extends ExtensionName>({
+  name,
+  params,
+  fallback,
+  loadingFallback,
+  errorFallback,
+}: ExtensionProps<TName>) {
+  const app = useApp();
+  const { Loading, Error } = app.components;
+
+  loadingFallback ??= <Loading kind="extension" />;
+  errorFallback ??= <Error kind="extension" />;
+
+  const extensionComponents = useMemo(() => {
+    return app.modules
+      .flatMap((m) => m.extensions)
+      .filter((registration) => registration.name === name)
+      .map((registration) => registration.component) as Array<ComponentType<ExtensionComponentProps<ExtensionName>>>;
+  }, [name, app.modules]);
+
+  if (extensionComponents.length === 0) {
+    return fallback;
+  }
+
+  return (
+    <ErrorBoundary fallback={errorFallback ?? fallback}>
+      <Suspense fallback={loadingFallback ?? fallback}>
+        {extensionComponents.map((ExtensionComponent, index) => (
+          <ExtensionComponent key={index} params={params} />
+        ))}
+      </Suspense>
+    </ErrorBoundary>
+  );
+}

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

@@ -0,0 +1,2 @@
+export * from './Extension';
+export * from './types';

package/src/app/features/extensions/types.tsx

@@ -0,0 +1,52 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Maps extension keys to their corresponding component props.
+ * This interface can be extended by modules via declaration merging.
+ *
+ * ```ts
+ * declare module '@tiny-server/core' {
+ *   export interface ExtensionParamsMap {
+ *     'my-extension': MyExtensionProps;
+ *   }
+ * }
+ * ```
+ */
+export interface ExtensionParamsMap {}
+
+/**
+ * Defines all typed/known extension names.
+ */
+export type KnownExtensionName = keyof ExtensionParamsMap;
+
+/**
+ * Defines an extension name, both typed/known and untyped/unknown.
+ */
+export type ExtensionName = KnownExtensionName | (string & {});
+
+/**
+ * The parameters of the extension with the given `TName`.
+ */
+export type ExtensionParams<TName extends ExtensionName> = TName extends KnownExtensionName
+  ? ExtensionParamsMap[TName]
+  : Record<string, unknown>;
+
+export interface ExtensionComponentProps<TName extends ExtensionName> {
+  /**
+   * The parameters to be forwarded to the extension component.
+   */
+  params: ExtensionParams<TName>;
+}
+
+export interface ExtensionRegistration<TName extends ExtensionName> {
+  /**
+   * The name of the extension to be registered.
+   */
+  name: TName;
+  /**
+   * The component to be rendered for the extension.
+   */
+  component: ComponentType<ExtensionComponentProps<TName>>;
+}
+
+export type AnyExtensionRegistration = { [Key in ExtensionName]: ExtensionRegistration<Key> }[ExtensionName];

package/src/app/features/index.ts

@@ -0,0 +1,6 @@
+export * from './extensions';
+export * from './layout';
+export * from './menu';
+export * from './modals';
+export * from './query';
+export * from './router';

package/src/app/features/layout/Error.tsx

@@ -0,0 +1,20 @@
+export interface ErrorKindMap {
+  unknown: '';
+  app: '';
+  route: '';
+  ['route-not-found']: '';
+  ['route-forbidden']: '';
+  extension: '';
+  menu: '';
+  modal: '';
+}
+
+export type ErrorKind = keyof ErrorKindMap;
+
+export interface ErrorProps {
+  kind: ErrorKind;
+}
+
+export function DefaultError({ kind }: ErrorProps) {
+  return <>Error: {kind}</>;
+}

package/src/app/features/layout/Layout.tsx

@@ -0,0 +1,7 @@
+import type { PropsWithChildren } from 'react';
+
+export interface LayoutProps extends PropsWithChildren {}
+
+export function DefaultLayout({ children }: LayoutProps) {
+  return <>{children}</>;
+}

package/src/app/features/layout/Loading.tsx

@@ -0,0 +1,21 @@
+import { LoadingOverlay } from '@mantine/core';
+
+export interface LoadingKindMap {
+  unknown: '';
+  app: '';
+  route: '';
+  page: '';
+  extension: '';
+  menu: '';
+  modal: '';
+}
+
+export type LoadingKind = keyof LoadingKindMap;
+
+export interface LoadingProps {
+  kind: LoadingKind;
+}
+
+export function DefaultLoading() {
+  return <LoadingOverlay visible />;
+}

package/src/app/features/layout/Page.tsx

@@ -0,0 +1,42 @@
+import { Container, Group, Grid, GridCol, Stack, Title, Box } from '@mantine/core';
+import { Suspense, type PropsWithChildren, type ReactNode } from 'react';
+import { useApp } from '../../context';
+
+export interface PageProps extends PropsWithChildren {
+  header?: ReactNode;
+  actions?: ReactNode;
+}
+
+export function DefaultPage({ header, actions, children }: PageProps) {
+  const { Loading } = useApp().components;
+
+  return (
+    <Box h="100%" p="xl">
+      <Container h="100%">
+        <Stack gap="xl">
+          <Grid gap="md" align="center">
+            <GridCol span={{ base: 12, md: 'auto' }}>
+              <Title
+                order={1}
+                textWrap="nowrap"
+                miw={0}
+                style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                {header}
+              </Title>
+            </GridCol>
+
+            <GridCol span={{ base: 12, md: 'content' }}>
+              <Group gap="md" wrap="wrap">
+                {actions}
+              </Group>
+            </GridCol>
+          </Grid>
+
+          <Suspense fallback={<Loading kind="page" />}>
+            <div>{children}</div>
+          </Suspense>
+        </Stack>
+      </Container>
+    </Box>
+  );
+}

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

@@ -0,0 +1,6 @@
+export * from './Error';
+export * from './initializer';
+export * from './Layout';
+export * from './Loading';
+export * from './Page';
+export * from './types';

package/src/app/features/layout/initializer.ts

@@ -0,0 +1,12 @@
+import type { AppInitializer } from '../../types';
+import { DefaultError } from './Error';
+import { DefaultLayout } from './Layout';
+import { DefaultLoading } from './Loading';
+import { DefaultPage } from './Page';
+
+export const layoutInitializer: AppInitializer = (app) => {
+  app.components.Error ??= DefaultError;
+  app.components.Layout ??= DefaultLayout;
+  app.components.Loading ??= DefaultLoading;
+  app.components.Page ??= DefaultPage;
+};

package/src/app/features/layout/types.ts

@@ -0,0 +1,14 @@
+import type { ComponentType } from 'react';
+import type { ErrorProps } from './Error';
+import type { LayoutProps } from './Layout';
+import type { LoadingProps } from './Loading';
+import type { PageProps } from './Page';
+
+declare module '../../types' {
+  export interface AppComponents {
+    Error: ComponentType<ErrorProps>;
+    Layout: ComponentType<LayoutProps>;
+    Loading: ComponentType<LoadingProps>;
+    Page: ComponentType<PageProps>;
+  }
+}