@tiny-server/core 0.0.0

package/src/utils/usePagination.ts

@@ -0,0 +1,64 @@
+import { useCallback } from 'react';
+import { useSearchParams } from 'react-router';
+
+export interface UsePaginationOptions {
+  /**
+   * The default name of the page query parameter in the URL.
+   * @default 'page'
+   */
+  pageParamName?: string;
+  /**
+   * The default name of the page size query parameter in the URL.
+   * @default 'pageSize'
+   */
+  pageSizeParamName?: string;
+  /**
+   * The default page value to be used as a fallback for missing values.
+   * @default 1
+   */
+  defaultPage?: number;
+  /**
+   * The default page size value to be used as a fallback for missing values.
+   * @default 20
+   */
+  defaultPageSize?: number;
+}
+
+/**
+ * Manages pagination query parameters for handling page and page size values in the URL.
+ */
+export function usePagination({
+  pageParamName = 'page',
+  pageSizeParamName = 'pageSize',
+  defaultPage = 1,
+  defaultPageSize = 20,
+}: UsePaginationOptions = {}) {
+  const [params, setParams] = useSearchParams();
+
+  const parsedPage = +(params.get(pageParamName) || defaultPage);
+  const parsedPageSize = +(params.get(pageSizeParamName) || defaultPageSize);
+  const page = isNaN(parsedPage) ? defaultPage : parsedPage;
+  const pageSize = isNaN(parsedPageSize) ? defaultPageSize : parsedPageSize;
+
+  const setPage = useCallback(
+    (newPage: number) => {
+      setParams((params) => {
+        params.set(pageParamName, newPage.toString());
+        return params;
+      });
+    },
+    [pageParamName, setParams],
+  );
+
+  const setPageSize = useCallback(
+    (newPageSize: number) => {
+      setParams((params) => {
+        params.set(pageSizeParamName, newPageSize.toString());
+        return params;
+      });
+    },
+    [pageSizeParamName, setParams],
+  );
+
+  return { page, pageSize, setPage, setPageSize };
+}

package/src/utils/useSearch.ts

@@ -0,0 +1,40 @@
+import { useCallback } from 'react';
+import { useSearchParams } from 'react-router';
+
+export interface UseSearchOptions {
+  /**
+   * The default name of the search query parameter in the URL.
+   * @default 'search'
+   */
+  searchParamName?: string;
+  /**
+   * The default search value to be used as a fallback for missing values.
+   * @default ''
+   */
+  defaultSearch?: string;
+}
+
+/**
+ * Manages a "search" query parameter used for filtering and searching page content.
+ */
+export function useSearch({ searchParamName = 'search', defaultSearch = '' }: UseSearchOptions = {}) {
+  const [params, setParams] = useSearchParams();
+
+  const search = params.get(searchParamName) || defaultSearch;
+
+  const setSearch = useCallback(
+    (newSearch: string) => {
+      setParams((params) => {
+        if (newSearch && newSearch !== defaultSearch) {
+          params.set(searchParamName, newSearch);
+        } else {
+          params.delete(searchParamName);
+        }
+        return params;
+      });
+    },
+    [defaultSearch, searchParamName, setParams],
+  );
+
+  return { search, setSearch };
+}

package/src/utils/useSession.ts

@@ -0,0 +1,42 @@
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { readSessionStateQuery, type Permission, type SessionRead, type SessionState } from '../api';
+
+/**
+ * Returns the app's current {@link SessionState}.
+ * This is a convenience hook which returns the data of the current {@link readSessionStateQuery}.
+ */
+export function useSessionState(): SessionState {
+  const { data } = useSuspenseQuery(readSessionStateQuery());
+  return data;
+}
+
+/**
+ * Returns the app's active {@link SessionRead} session data.
+ *
+ * **⚠️ Important**:
+ * This hook should only be used in components which are guaranteed to be rendered in an active session context.
+ * If no active session exists, this hook will throw an error.
+ */
+export function useSession(): SessionRead {
+  const sessionState = useSessionState();
+
+  if (!sessionState.hasSession) {
+    throw new Error(
+      'useSession was called, but no active user session exists. ' +
+        'This hook should only be called in components which are guaranteed to be rendered in an active session context.',
+    );
+  }
+
+  return sessionState.session;
+}
+
+/**
+ * Returns the app's active session's permissions.
+ *
+ * **⚠️ Important**:
+ * This hook should only be used in components which are guaranteed to be rendered in an active session context.
+ * If no active session exists, this hook will throw an error.
+ */
+export function usePermissions(): Array<Permission> {
+  return useSession().permissions;
+}