@tiny-server/core 0.0.0

package/dist/api/apiResults.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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/dist/api/entity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export interface EntityCreate {
+}
+/**
+ * Represents data for updating an entity.
+ */
+export interface EntityUpdate {
+}

package/dist/api/index.d.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/dist/api/paginationOptions.d.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/dist/api/permissions.d.ts

@@ -0,0 +1,55 @@
+import { 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 declare function readPermissions(): Promise<ListApiResult<PermissionRead>>;
+/** {@link readPermissions} */
+export declare function readPermissionsQuery(): import('@tanstack/query-core').OmitKeyof<import('@tanstack/react-query').UseQueryOptions<ListApiResult<PermissionRead>, Error, ListApiResult<PermissionRead>, string[]>, "queryFn"> & {
+    queryFn?: import('@tanstack/query-core').QueryFunction<ListApiResult<PermissionRead>, string[], never> | undefined;
+} & {
+    queryKey: string[] & {
+        [dataTagSymbol]: ListApiResult<PermissionRead>;
+        [dataTagErrorSymbol]: Error;
+    };
+};

package/dist/api/problemDetails.d.ts

@@ -0,0 +1,16 @@
+/**
+ *  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 declare function isProblemDetails(obj: unknown): obj is ProblemDetails;

package/dist/api/session.d.ts

@@ -0,0 +1,38 @@
+import { 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 declare function readSessionState(): Promise<SessionState>;
+/** {@link readSessionState} */
+export declare function readSessionStateQuery(): import('@tanstack/query-core').OmitKeyof<import('@tanstack/react-query').UseQueryOptions<SessionState, Error, SessionState, string[]>, "queryFn"> & {
+    queryFn?: import('@tanstack/query-core').QueryFunction<SessionState, string[], never> | undefined;
+} & {
+    queryKey: string[] & {
+        [dataTagSymbol]: SessionState;
+        [dataTagErrorSymbol]: Error;
+    };
+};

package/dist/api/sortOptions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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/dist/api/status.d.ts

@@ -0,0 +1,27 @@
+import { Permission } from './permissions';
+import { 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 declare function readStatus(): Promise<ApiResult<StatusRead>>;
+/** {@link readStatus} */
+export declare function readStatusQuery(): import('@tanstack/query-core').OmitKeyof<import('@tanstack/react-query').UseQueryOptions<ApiResult<StatusRead>, Error, ApiResult<StatusRead>, string[]>, "queryFn"> & {
+    queryFn?: import('@tanstack/query-core').QueryFunction<ApiResult<StatusRead>, string[], never> | undefined;
+} & {
+    queryKey: string[] & {
+        [dataTagSymbol]: ApiResult<StatusRead>;
+        [dataTagErrorSymbol]: Error;
+    };
+};

package/dist/app/App.d.ts

@@ -0,0 +1,12 @@
+import { AppInstance } from './types';
+import { 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 declare function App({ app, children }: AppProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/context.d.ts

@@ -0,0 +1,6 @@
+import { AppInstance } from './types';
+export declare const appContext: import('react').Context<AppInstance>;
+/**
+ * Retrieves the configured {@link AppInstance}.
+ */
+export declare function useApp(): AppInstance;

package/dist/app/create.d.ts

@@ -0,0 +1,12 @@
+import { 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 declare function createApp(modules: Array<Module>): AppInstance;
+/**
+ * Creates a fully configured {@link Module} based on the given {@link ModuleInit}.
+ * @param moduleInit The configuration with which to initialize the module.
+ */
+export declare function createModule(moduleInit: ModuleInit): Module;

package/dist/app/features/extensions/Extension.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+import { ExtensionName, ExtensionParams } from './types';
+export interface ExtensionProps<TName extends ExtensionName | (string & {})> {
+    /**
+     * The name of the extension to render.
+     */
+    name: TName;
+    /**
+     * The parameters to be forwarded to the extension component.
+     */
+    params: TName extends ExtensionName ? ExtensionParams<TName> : Record<string, unknown>;
+    /**
+     * 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 declare function Extension<Name extends ExtensionName | (string & {})>({ name, params, fallback, loadingFallback, errorFallback, }: ExtensionProps<Name>): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;

package/dist/app/features/extensions/index.d.ts

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

package/dist/app/features/extensions/types.d.ts

@@ -0,0 +1,43 @@
+import { 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 {
+    '': never;
+}
+/**
+ * Defines all known extension names.
+ */
+export type ExtensionName = keyof ExtensionParamsMap;
+/**
+ * The parameters of the extension with the given `TName`.
+ */
+export type ExtensionParams<TName extends ExtensionName> = ExtensionParamsMap[TName];
+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/dist/app/features/index.d.ts

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

package/dist/app/features/layout/Error.d.ts

@@ -0,0 +1,15 @@
+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 declare function DefaultError({ kind }: ErrorProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/layout/Layout.d.ts

@@ -0,0 +1,4 @@
+import { PropsWithChildren } from 'react';
+export interface LayoutProps extends PropsWithChildren {
+}
+export declare function DefaultLayout({ children }: LayoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/layout/Loading.d.ts

@@ -0,0 +1,14 @@
+export interface LoadingKindMap {
+    unknown: '';
+    app: '';
+    route: '';
+    page: '';
+    extension: '';
+    menu: '';
+    modal: '';
+}
+export type LoadingKind = keyof LoadingKindMap;
+export interface LoadingProps {
+    kind: LoadingKind;
+}
+export declare function DefaultLoading(): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/layout/Page.d.ts

@@ -0,0 +1,6 @@
+import { PropsWithChildren, ReactNode } from 'react';
+export interface PageProps extends PropsWithChildren {
+    header?: ReactNode;
+    actions?: ReactNode;
+}
+export declare function DefaultPage({ header, actions, children }: PageProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/layout/index.d.ts

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

package/dist/app/features/layout/initializer.d.ts

@@ -0,0 +1,2 @@
+import { AppInitializer } from '../../types';
+export declare const layoutInitializer: AppInitializer;

package/dist/app/features/layout/types.d.ts

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

package/dist/app/features/menu/Menu.d.ts

@@ -0,0 +1,7 @@
+import { MenuComponentProps, MenuType } from './types';
+export interface MenuProps<TMenuType extends MenuType = MenuType> extends MenuComponentProps<TMenuType> {
+}
+/**
+ * Renders the menu of the given type.
+ */
+export declare function Menu({ type, params }: MenuProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/menu/MenuContainer.d.ts

@@ -0,0 +1,4 @@
+import { MenuComponentProps, MenuType } from '.';
+export interface MenuContainerProps<TMenuType extends MenuType = MenuType> extends MenuComponentProps<TMenuType> {
+}
+export declare function DefaultMenuContainer<TMenuType extends MenuType = MenuType>({ children, }: MenuContainerProps<TMenuType>): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/menu/MenuItem.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { MenuItemComponentProps, MenuType } from '../../..';
+export interface MenuItemProps<TMenuType extends MenuType = MenuType> extends MenuItemComponentProps<TMenuType> {
+    label?: ReactNode;
+    description?: ReactNode;
+    leftSection?: ReactNode;
+    rightSection?: ReactNode;
+    to?: string;
+    onClick?: () => void;
+}
+export declare function DefaultMenuItem<TMenuType extends MenuType = MenuType>({ id, label, description, leftSection, rightSection, to, onClick, children, }: MenuItemProps<TMenuType>): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/menu/index.d.ts

@@ -0,0 +1,5 @@
+export * from './initializer';
+export * from './Menu';
+export * from './MenuContainer';
+export * from './MenuItem';
+export * from './types';

package/dist/app/features/menu/initializer.d.ts

@@ -0,0 +1,2 @@
+import { AppInitializer } from '../../types';
+export declare const menuInitializer: AppInitializer;

package/dist/app/features/menu/types.d.ts

@@ -0,0 +1,71 @@
+import { ComponentType, PropsWithChildren } from 'react';
+import { MenuContainerProps } from './MenuContainer';
+import { MenuItemProps } from './MenuItem';
+declare module '../../types' {
+    interface AppComponents {
+        MenuContainer: ComponentType<MenuContainerProps>;
+        MenuItem: ComponentType<MenuItemProps>;
+    }
+}
+/**
+ * A map of all known menus.
+ * This interface can be extended by modules via declaration merging.
+ *
+ * ```ts
+ * declare module '@tiny-server/core' {
+ *   export interface MenuParamsMap {
+ *     'my-menu': MyMenuParams;
+ *   }
+ * }
+ * ```
+ */
+export interface MenuParamsMap {
+    default: {};
+}
+/**
+ * Defines all known menu types.
+ */
+export type MenuType = keyof MenuParamsMap;
+/**
+ * The parameters of the menu with the given `TType`.
+ */
+export type MenuParams<TType extends MenuType> = MenuParamsMap[TType];
+export interface MenuComponentProps<TMenuType extends MenuType = MenuType> extends PropsWithChildren {
+    /**
+     * The type of the menu that the item belongs to.
+     */
+    type: TMenuType;
+    /**
+     * The parameters to be forwarded to the menu item component.
+     */
+    params: MenuParams<TMenuType>;
+}
+export interface MenuItemComponentProps<TMenuType extends MenuType = MenuType> extends MenuComponentProps<TMenuType> {
+    /**
+     * The unique identifier of the menu item.
+     */
+    id: string;
+}
+export interface MenuItemRegistration<TMenuType extends MenuType> {
+    /**
+     * A unique identifier for the menu item.
+     */
+    id: string;
+    /**
+     * The unique identifier of the parent menu item.
+     * Must reference an existing parent menu item within the same menu.
+     * If no parent is found, the child is not rendered.
+     */
+    parentId?: string;
+    /**
+     * The menu that the item belongs to.
+     */
+    menu: TMenuType;
+    /**
+     * The component to be rendered for the menu item.
+     */
+    component: ComponentType<MenuItemComponentProps<TMenuType>>;
+}
+export type AnyMenuItemRegistration = {
+    [TMenuType in MenuType]: MenuItemRegistration<TMenuType>;
+}[MenuType];

package/dist/app/features/modals/Modal.d.ts

@@ -0,0 +1,5 @@
+import { ModalComponentProps, ModalName, ModalOptions } from '.';
+export interface ModalProps<TModalName extends ModalName = ModalName> extends ModalComponentProps<TModalName> {
+    options?: ModalOptions;
+}
+export declare function DefaultModal({ name, params, options, onClose }: ModalProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/modals/ModalBody.d.ts

@@ -0,0 +1,4 @@
+import { PropsWithChildren } from 'react';
+export interface ModalBodyProps extends PropsWithChildren {
+}
+export declare function DefaultModalBody({ children }: ModalBodyProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/modals/ModalContent.d.ts

@@ -0,0 +1,7 @@
+import { ModalComponentProps, ModalName } from './types';
+export interface ModalContentProps<TModalName extends ModalName = ModalName> extends ModalComponentProps<TModalName> {
+}
+/**
+ * Renders registered modal content.
+ */
+export declare function ModalContent({ name, params, onClose }: ModalContentProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/modals/ModalFooter.d.ts

@@ -0,0 +1,5 @@
+import { PropsWithChildren, ReactNode } from 'react';
+export interface ModalFooterProps extends PropsWithChildren {
+    actions?: ReactNode;
+}
+export declare function DefaultModalFooter({ children, actions }: ModalFooterProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/modals/ModalHeader.d.ts

@@ -0,0 +1,5 @@
+import { ReactNode } from 'react';
+export interface ModalHeaderProps {
+    title?: ReactNode;
+}
+export declare function DefaultModalHeader({ title }: ModalHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/modals/Modals.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Renders all currently opened application modals.
+ */
+export declare function Modals(): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/modals/index.d.ts

@@ -0,0 +1,8 @@
+export * from './initializer';
+export * from './Modal';
+export * from './ModalBody';
+export * from './ModalContent';
+export * from './ModalFooter';
+export * from './ModalHeader';
+export * from './Modals';
+export * from './types';

package/dist/app/features/modals/initializer.d.ts

@@ -0,0 +1,2 @@
+import { AppInitializer } from '../../types';
+export declare const modalsInitializer: AppInitializer;

package/dist/app/features/modals/store.d.ts

@@ -0,0 +1,14 @@
+import { ModalName, ModalParams } from './types';
+interface OpenModal<TModalName extends ModalName = ModalName> {
+    id: string;
+    name: TModalName;
+    params: ModalParams<TModalName>;
+}
+interface ModalsStore {
+    _lastId: number;
+    modals: Array<OpenModal>;
+    openModal<TModalName extends ModalName>(name: TModalName, params: ModalParams<TModalName>): string;
+    closeModal(id: string): void;
+}
+export declare const modalsStore: import('zustand').StoreApi<ModalsStore>;
+export {};