katanakit-js 2.1.6 → 2.12.9

package/README.md

@@ -1,61 +1,6 @@
-# KatanaKit (`katanakit-js`)
-
-KatanaKit is a sharp, framework-agnostic **TypeScript service toolkit** organized
-with **hexagonal architecture** and built on proven design patterns (Singleton,
-Observer, Factory, Strategy, Facade and Adapter).
-
-It runs in the browser, in Node.js (>= 22.18) and in Bun, ships with an Astro
-`getStaticPaths` adapter, an RSS 2.0 generator, a site-config/SEO module, an
-optional Express server reference and a Nuxt (Nitro/H3) adapter. Importing a
-module never triggers side effects, and every async operation returns a **Safe
-Result** instead of throwing.
-
-- **Version:** 2.1.4
-- **npm package:** `katanakit-js`
-- **Repository:** [senseikatana/katanakit](https://github.com/senseikatana/katanakit)
-  (development happens on the `dev` branch)
-- **License:** MIT
-
-## Why
-
-Modern frontend and full-stack apps keep reimplementing the same plumbing:
-fetching an API safely, logging, persisting to storage, querying the DOM,
-reacting to state changes, generating slugs, formatting dates and money,
-building RSS/SEO output. KatanaKit provides all of that as a single, typed and
-tree-shakeable set of `use*` services with a consistent API: one `useInit` for
-your APIs, one `useFetch` that returns a Safe Result, one way to do logging,
-storage and DOM across every framework.
+# `katanakit-js`
 
-## Features
-
-- **Safe URL construction** — builds URLs from a JSON-defined API registry using
-  the native `URL` API and `encodeURIComponent`; only `http:`/`https:` schemes
-  are allowed (prevents `javascript:` URLs and SSRF).
-- **Safe Result** — every `useFetch` returns a discriminated union
-  `{ data, error, url, status, ok }` (Astro Actions style) instead of throwing
-  on HTTP errors.
-- **Hexagonal architecture** — a pure `core` layer (services), an
-  `infrastructure` layer (browser/runtime adapters), an `adapters` layer
-  (Astro, Express, Nuxt), a `config` layer (site config + SEO) and a single
-  source of truth for contracts and types in `src/types/`.
-- **Design patterns** — Singleton facades, Strategy (logger, storage,
-  crypto/UUID), Factory (errors, debounce/throttle), Observer (signals,
-  IntersectionObserver, media queries), Facade and Adapter, all exposed as
-  `use*` methods (like React hooks) with safe destructured exports.
-- **Consistent `use*` API** — every public method is prefixed with `use`
-  (`useInit`, `useFetch`, `useLog`, `useCreateSignal`, ...); the only exception
-  is `getInstance()`.
-- **Pure ESM** — relative imports use explicit `.js` extensions and
-  `module: nodenext`; bundlers and Node resolve the package cleanly.
-- **Zero side effects on import** — importing a module never triggers network
-  calls, timers, storage writes or DOM mutations.
-- **SSR-safe** — browser-only adapters guard or fall back gracefully
-  (in-memory storage, main-thread worker execution) when `window` is
-  unavailable.
-- **Optional heavy dependencies** — only `@js-temporal/polyfill` is a runtime
-  dependency; `express`, `cors`, `dotenv` and `@prisma/orm-postgres` are
-  optional peer dependencies.
-- **Fully typed** — strict TypeScript with generated `.d.ts` declarations.
+A sharp, framework-agnostic TypeScript service toolkit organized with hexagonal architecture.
 
 ## Installation
 
@@ -63,384 +8,127 @@ storage and DOM across every framework.
 npm install katanakit-js
 # or
 bun add katanakit-js
+# or
+yarn add katanakit-js
 ```
 
-Requirements: **Node.js >= 22.18.0** (pure ESM package). TypeScript consumers
-should use `moduleResolution: "nodenext"` (or `"bundler"`).
+### CDN (ESM)
 
-### Framework adapters
+In the browser, use jsDelivr **`/+esm`** so named exports and dependencies resolve:
 
-The root import is framework-agnostic. Framework-specific entry points are
-published as package **subpaths** of the same `katanakit-js` package:
-
-```ts
-// Nuxt / Nitro adapter helpers (no extra dependency; h3 ships with Nuxt)
-import { useUnwrap } from "katanakit-js/adapters/nuxt";
-
-// Express reference server (requires express as a peer dependency)
-import { ServerExpress } from "katanakit-js/adapters/express";
+```html
+<script type="module">
+  import { useLogger, useGetApi, useInitApis } from "https://cdn.jsdelivr.net/npm/katanakit-js/+esm";
+  useLogger("ready");
+</script>
 ```
 
-`express`, `cors`, `dotenv` and `@prisma/orm-postgres` are **optional peer
-dependencies** — install them only if you use the Express adapter or the Prisma
-layer.
-
-### Building from source
+| CDN | URL |
+|-----|-----|
+| **jsDelivr `/+esm`** (recommended) | `https://cdn.jsdelivr.net/npm/katanakit-js/+esm` |
+| **esm.sh** | `https://esm.sh/katanakit-js` |
+| **Raw ESM file** | `https://cdn.jsdelivr.net/npm/katanakit-js/dist/index.js` (needs bundler or import map) |
 
-```bash
-git clone https://github.com/senseikatana/katanakit.git
-cd katanakit
-bun install
-bun run build       # outputs to dist/
-```
+Pin a version in production (e.g. `@2.8.0/+esm`). There is no IIFE/UMD build.
 
 ## Quick Start
 
-Everything below is importable from the main barrel `katanakit-js`.
-
-### HTTP client
-
 ```ts
-import { useInit, useGet, usePost, useBuildUrl } from "katanakit-js";
+import { useInitApis, useGetApi, useLogger } from "katanakit-js";
+
+useLogger("boot");
 
-// 1. Register your APIs once.
-useInit({
+// Register your APIs once
+useInitApis({
   pokeapi: {
     baseUri: "https://pokeapi.co/api/v2",
-    endpoints: {
-      pokemonById: "/pokemon/:id/",
-      pokemons: "/pokemons/",
-    },
+    endpoints: { pokemonById: "/pokemon/:id/" },
   },
 });
 
-// 2. Build a safe URL (path params encoded, query params merged).
-const url = useBuildUrl("pokeapi", "pokemonById", {
-  params: { id: "pikachu" },
-});
-// => "https://pokeapi.co/api/v2/pokemon/pikachu/"
-
-// 3. Fetch with a Safe Result (no throwing on HTTP errors).
-const result = await useGet<{ name: string }>("pokeapi", "pokemonById", {
+// Fetch with Safe Result — no try/catch needed for HTTP failures
+const result = await useGetApi<{ name: string }>("pokeapi", "pokemonById", {
   params: { id: 25 },
 });
 
 if (result.ok) {
-  console.log(result.data.name);
+  console.log(result.data.name); // "pikachu"
 } else {
-  console.error(result.error.message, result.error.status);
+  console.error(result.error.message);
 }
-
-// 4. POST JSON.
-await usePost("pokeapi", "pokemons", { name: "charmander" });
 ```
 
-### Logger, storage and DOM
-
-```ts
-import {
-  useLog,
-  useSetStorage,
-  useGetStorage,
-  useRemoveStorage,
-  useAddClass,
-  useGetRoot,
-} from "katanakit-js";
-
-useLog("Hello", { user: "John" });                  // info level
-useLog("error", "Something failed", { code: 500 }); // error level
-
-useSetStorage("theme", "dark");
-const theme = useGetStorage<string>("theme");       // "dark"
-useRemoveStorage("theme");
-
-useAddClass(useGetRoot()!, "dark-mode");
-```
-
-Storage is SSR-safe: when `window` is unavailable an in-memory fallback is used
-automatically, so imports never crash in Node/Bun.
-
-## Astro adapter
-
-KatanaKit converts arbitrary collections into the payload Astro's
-`getStaticPaths` expects, wrapped in a Safe Result.
-
-```ts
-// src/pages/blog/[slug].astro
-import { AstroService } from "katanakit-js";
-
-export async function getStaticPaths() {
-  const { useGetStaticPaths } = AstroService.getInstance();
-
-  return useGetStaticPaths(getCollection, "blog", {
-    param: "slug",
-    valueFrom: (entry) => entry.slug ?? entry.id,
-    propsFrom: (entry) => entry.data,
-  });
-}
-```
-
-Also available: `usePathsFrom`, `useFindEntry`, `useGeneratePagination`,
-`usePathsFromValues` and `useExtractUniqueValues`. See the
-[API Reference](docs/API-Reference.md#astro--astroservice).
+## Features
 
-## RSS feeds for Astro
+- **Safe Results** — HTTP (and other fallible) operations return `{ data, error, ok }` instead of throwing
+- **Zero side effects** — importing any module is safe. No `fetch` calls, no `console.log`, no storage writes
+- **Hexagonal architecture** — pure core, infrastructure adapters, framework adapters
+- **Tree-shakeable** — destructured re-exports from Singleton facades
+- **SSR-safe** — all infrastructure adapters guard or fall back gracefully in server environments
 
-`RssService` generates pure RSS 2.0 XML with **no external dependencies**
-(`@astrojs/rss` is not required).
+## Framework usage
 
-```ts
-// src/pages/rss.xml.ts
-import { RssService } from "katanakit-js";
-import { getCollection } from "astro:content";
-
-const { useCreateRssEndpoint } = RssService.getInstance();
-
-export const GET = useCreateRssEndpoint({
-  title: "My Blog",
-  description: "Posts about TypeScript",
-  site: "https://example.com",
-  items: async () => {
-    const posts = await getCollection("blog");
-    return posts.map((post) => ({
-      title: post.data.title,
-      pubDate: post.data.date,
-      link: `/blog/${post.slug}/`,
-      description: post.data.description,
-    }));
-  },
-});
-```
+All common `use*` helpers (`useLogger`, `useInitApis`, `useGetApi`, formatter, dates, utils, theme, …) are on the **main barrel** `katanakit-js`.
 
-Add the feed `<link>` tag to your layout's `<head>`:
+### Astro (npm)
 
 ```astro
 ---
-import { useRssLinkTag } from "katanakit-js";
+// Frontmatter = server
+import { useLogger, useGetApi, useInitApis } from "katanakit-js";
+useInitApis({ /* ... */ });
+const result = await useGetApi("pokeapi", "pokemonById", { params: { id: 25 } });
 ---
-<head>
-  <Fragment set:html={useRssLinkTag({ title: "My Blog" })} />
-</head>
-```
-
-`useCreateRssEndpointFromConfig(siteConfig, items)` builds the same endpoint
-from your `SiteConfig`. See the [API Reference](docs/API-Reference.md#rss--rssservice).
-
-## Site config and SEO
-
-Centralize your site metadata in a typed `SiteConfig` and derive every `<head>`
-tag from it.
-
-```ts
-// src/config/site.config.ts
-import { type SiteConfig } from "katanakit-js";
-
-export const siteConfig: SiteConfig = {
-  site: "https://myblog.com",
-  title: "My Blog",
-  description: "A blog about TypeScript and Astro",
-  lang: "en",
-  author: "John Doe",
-  ogImage: "/og-default.png",
-  twitter: "johndoe",
-  rss: { enabled: true, path: "/rss.xml", limit: 20 },
-  seo: { noindex: false, canonical: true, openGraph: true, twitterCard: true, jsonLd: true },
-  nav: [
-    { label: "Home", href: "/" },
-    { label: "Blog", href: "/blog" },
-    { label: "GitHub", href: "https://github.com/senseikatana/katanakit", external: true },
-  ],
-};
+<script>
+  // Client script — Vite bundles the same package
+  import { useLogger } from "katanakit-js";
+  useLogger("client");
+</script>
 ```
 
-Then inject complete meta tags (title, description, canonical, Open Graph,
-Twitter Card and JSON-LD) in your layout:
+### Astro (CDN client)
 
 ```astro
----
-// src/layouts/BaseLayout.astro
-import { siteConfig } from "@/config/site.config";
-import { useHeadTags } from "katanakit-js";
-
-interface Props {
-  title: string;
-  description?: string;
-  ogType?: "website" | "article";
-  publishedTime?: string;
-}
-
-const { title, description, ogType, publishedTime } = Astro.props;
-const headTags = useHeadTags(siteConfig, {
-  title,
-  description,
-  url: new URL(Astro.url.pathname, siteConfig.site).href,
-  ogType,
-  publishedTime,
-});
----
-<html lang={siteConfig.lang}>
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <Fragment set:html={headTags} />
-</head>
-<body>
-  <slot />
-</body>
-</html>
+<script is:inline type="module">
+  import { useLogger } from "https://cdn.jsdelivr.net/npm/katanakit-js/+esm";
+  useLogger("cdn");
+</script>
 ```
 
-The RSS endpoint consumes the same config:
+### Vue / Nuxt / vanilla
 
 ```ts
-// src/pages/rss.xml.ts
-import { RssService } from "katanakit-js";
-import { siteConfig } from "@/config/site.config";
-import { getCollection } from "astro:content";
-
-const { useCreateRssEndpointFromConfig } = RssService.getInstance();
-
-export const GET = useCreateRssEndpointFromConfig(siteConfig, async () => {
-  const posts = await getCollection("blog");
-  return posts.map((post) => ({
-    title: post.data.title,
-    pubDate: post.data.date,
-    link: `/blog/${post.slug}/`,
-    description: post.data.description,
-  }));
-});
+import { useLogger, useInitApis, useGetApi } from "katanakit-js";
+import { useKatanaFetch } from "katanakit-js/adapters/vue";   // Vue only
+import { useUnwrap } from "katanakit-js/adapters/nuxt";         // Nuxt only
 ```
 
-## Nuxt adapter
-
-New in 2.1.4. Three pure helper functions bridge KatanaKit's Safe Results to
-Nuxt/Nitro server routes. They are **not** singleton services — just exported
-functions — and they avoid a hard dependency on `h3` (it ships with Nuxt).
-
-```ts
-import { useInit, useGet } from "katanakit-js";
-import { useUnwrap } from "katanakit-js/adapters/nuxt";
-
-// server/plugins/api.ts — register your APIs once
-useInit({
-  pokeapi: {
-    baseUri: "https://pokeapi.co/api/v2",
-    endpoints: { pokemonById: "/pokemon/:id/" },
-  },
-});
+```html
+<!-- vanilla -->
+<script type="module">
+  import { useLogger } from "https://cdn.jsdelivr.net/npm/katanakit-js/+esm";
+</script>
 ```
 
-```ts
-// server/api/pokemon/[id].ts
-import { useGet } from "katanakit-js";
-import { useUnwrap } from "katanakit-js/adapters/nuxt";
-
-export default defineEventHandler(async (event) => {
-  const id = getRouterParam(event, "id");
-  const result = await useGet("pokeapi", "pokemonById", { params: { id } });
-  return useUnwrap(result, `Pokemon ${id}`); // returns data, or throws an H3-compatible error
-});
-```
+See [Getting Started](https://senseikatana.github.io/katanakit-js/docs/guides/getting-started) for full recipes.
 
-The other helpers are `useSafeResponse(result)` (shape the result as a clean
-JSON response object) and `useEventResponse(event, result)` (set the H3 event
-status code and return data/error). See the
-[API Reference](docs/API-Reference.md#nuxt-adapter--katanakit-jsadaptersnuxt).
+## Framework Adapters
 
-## Express server (optional)
-
-The Express reference adapter is exposed only through its own subpath so it
-never bloats the main bundle:
-
-```ts
-import { ServerExpress } from "katanakit-js/adapters/express";
-
-ServerExpress.getInstance().useStart(); // http://localhost:3000
-```
-
-It expects `express` (and `cors`/`dotenv` if used) to be installed in your
-project. A `ProductController` and a demo `router` are also exported.
-
-## Services at a glance
-
-| Area      | Service / module            | Highlights                                                          |
-| --------- | --------------------------- | ------------------------------------------------------------------- |
-| HTTP      | `FetchApiManager`           | `useInit`, `useGetApis`, `useBuildUrl`, `useFetch`, `useGet`, `usePost`, `usePut`, `useDelete` |
-| Logging   | `LoggerService`             | `useLog`, `useError`, `useClear`, `useTable`, pluggable `LogStrategy` |
-| Storage   | `StorageService`            | `useGetStorage`, `useSetStorage`, `useRemoveStorage`, `useClearStorage` (SSR-safe) |
-| DOM       | `DomService`                | `useQuerySelector`, `useAddClass`, `useOn`, `useSetText`, ...        |
-| Reactive  | `ReactiveService`           | `useCreateSignal`, `useCreateEffect`, `useCreateMemo`, `useCreateToggle`, `useCreateStorageSignal`, `useCreateDebouncedSignal`, `useCreateBatch` |
-| Format    | `FormatterService`          | `useFormatNumber`, `useFormatCurrency`, `useJsonStringify`, `useUpperCase`, `useCapitalize`, ... |
-| Convert   | `ConverterService`          | `useToCelsius`, `useToFahrenheit`, `useToMiles`, `useToKilos`, ...   |
-| Errors    | `ErrorFactoryService`       | `useBadRequest`, `useUnauthorized`, `useForbidden`, `useNotFound`, `useInternal`, `useCustom` |
-| Generate  | `GeneratorService`          | `useUuid`, `useSlugify`, `useNumericId`, `useToken`, `useEncrypt`    |
-| Dates     | `DatesService`              | `useFormat`, `useNow`, `useAddDays`, `useIsBefore`, `useLastDayOfMonth`, ... (Temporal) |
-| Geometry  | `GeometryUtils`             | `area`, `perimeter`, `volume` static helpers (`useCircle`, `useSphere`, ...) |
-| Timing    | `TimingService`             | `useDelay`, `useSetTimeout`, `useInterval`, `useDebounce`, `useThrottle`, `useRepeat`, `useRace` |
-| Utils     | `DataUtils` / `SystemUtils` | `useUnique`, `useGroupBy`, `useDeepClone`, `useSleep`, `useRetry`, `useRound`, ... |
-| Viewport  | `ViewportService`           | scroll, fullscreen, visibility, `usePrefersReducedMotion`            |
-| Sensors   | `SensorsUtils`              | `useGetGeolocation`, `useGetMediaStream`, `useVibrate`, `useGetBattery`, ... |
-| Observer  | `ObserverService`           | `useCreate`, `useObserve`, `useObserveAll`, `useDisconnect`          |
-| LazyLoad  | `LazyLoaderService`         | `useInit`, `useStop`, `useStopAll` for `img[data-src]`               |
-| Worker    | `WorkerService`             | `useRun`, `useCreatePool`, `useRunPool`, `useTerminate`              |
-| Theme     | `ThemeService`              | `useInitTheme`, `useSetThemeMode`, `useToggleTheme`, `useResetTheme` |
-| Astro     | `AstroService`              | `useGetStaticPaths`, `usePathsFrom`, `useGeneratePagination`, ...    |
-| RSS       | `RssService`                | `useGenerateRss`, `useRssLinkTag`, `useCreateRssEndpoint`, `useCreateRssEndpointFromConfig` |
-| SEO       | `useHeadTags` and friends   | `useGenerateMetaTags`, `useTitle`, `useRssHeadLink` + typed `SiteConfig` |
-| Config    | `siteConfig` / `SiteConfig` | single source for site metadata, RSS and SEO defaults                |
-| Nuxt      | `katanakit-js/adapters/nuxt`| `useUnwrap`, `useSafeResponse`, `useEventResponse` (pure functions)  |
-| Server    | `katanakit-js/adapters/express` | `ServerExpress`, `router`, `ProductController` (optional reference) |
-
-The Astro, RSS, SEO and config modules plus all core/infrastructure services
-are re-exported from the main barrel. The Nuxt and Express adapters are only
-available through their subpaths.
-
-## Project structure (hexagonal)
-
-```
-katanakit/
-├── package.json              # name: katanakit-js, ESM, exports map
-├── prisma.config.ts          # Prisma ORM config (contract + connection)
-├── src/
-│   ├── index.ts              # main barrel (public API)
-│   ├── types/                # single source of truth: contracts & types
-│   ├── core/
-│   │   └── services/         # pure services (no I/O): logger, http, ...
-│   ├── infrastructure/       # browser/runtime adapters
-│   │   ├── dom/  storage/  viewport/  sensors/
-│   │   └── observer/  worker/  theme/
-│   ├── adapters/             # framework adapters
-│   │   ├── astro/            #   AstroService + RssService
-│   │   ├── express/          #   ServerExpress reference (subpath export)
-│   │   └── nuxt/             #   Nuxt helpers (subpath export)
-│   ├── config/               # siteConfig (SiteConfig) + SEO helpers
-│   └── prisma/               # Prisma schema, contract types and db client
-├── tests/                    # Vitest suite (57 tests across 7 files)
-├── examples/                 # runnable demos
-├── docs/                     # Getting Started, Architecture, API Reference, Roadmap
-├── CONTRIBUTING.md
-└── SECURITY.md
-```
-
-All internal source imports are relative and carry an explicit `.js` extension
-(pure ESM, `module: nodenext`). The `@/` alias (mapped to `src/`) is configured
-for the test suite and the examples.
+| Adapter | Import | Description |
+|---------|--------|-------------|
+| **Express** | `katanakit-js/adapters/express` | Reference server with CORS and hardened headers |
+| **Nuxt** | `katanakit-js/adapters/nuxt` | `useUnwrap`, `useSafeResponse`, `useEventResponse` |
+| **Vue** | `katanakit-js/adapters/vue` | `useKatanaFetch` composable with reactivity |
+| **Astro** | `katanakit-js` or `katanakit-js/adapters/astro` | `AstroService`, `RssService` |
 
 ## Documentation
 
-- [Getting Started](docs/Getting-Started.md)
-- [Architecture](docs/Architecture.md)
-- [API Reference](docs/API-Reference.md)
-- [Roadmap](docs/Roadmap.md)
-- [Security](SECURITY.md)
-- [Changelog](CHANGELOG.md)
-
-## Contributing
-
-Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
-the development contract (hexagonal layering, `use*` convention, `.js` ESM
-imports, tests, scripts) before opening a pull request.
+- [Getting Started](https://senseikatana.github.io/katanakit-js/docs/guides/getting-started)
+- [Architecture](https://senseikatana.github.io/katanakit-js/docs/guides/architecture)
+- [API Reference](https://senseikatana.github.io/katanakit-js/docs/api)
+- [Roadmap](https://senseikatana.github.io/katanakit-js/docs/guides/roadmap)
+- [Changelog](https://senseikatana.github.io/katanakit-js/docs/changelog)
 
 ## License
 
-[MIT](LICENSE)
+MIT

package/dist/adapters/astro/astro.service.d.ts

@@ -1,18 +1,106 @@
-import type { AstroPath, AstroServiceResult, CollectionEntryLike, IAstroService, PaginationProps, PathsOptions } from "../../types/index.js";
+import type { AstroPath, AstroServiceResult, CollectionEntryLike, PaginationProps, PathsOptions } from "../../types/index.js";
 /**
- * Astro adapter (Facade + Adapter + Singleton). Converts arbitrary collections
- * into the `getStaticPaths` format Astro expects, wrapped in a Safe Result.
+ * Convert a collection into Astro-compatible static paths.
+ *
+ * @param items - Collection items to convert
+ * @param options - Configuration for param name, value extraction and props
+ * @returns Array of Astro paths with params and props
+ *
+ * @example
+ * ```ts
+ * // In Astro's getStaticPaths()
+ * const posts = await getCollection("blog");
+ * const paths = useAstroPathsFrom(posts, {
+ *   param: "slug",
+ *   valueFrom: (post) => post.slug,
+ *   propsFrom: (post) => ({ title: post.data.title }),
+ * });
+ * // [{ params: { slug: "hello-world" }, props: { title: "Hello World" } }]
+ * ```
  */
-export declare class AstroService implements IAstroService {
-    private static instance;
-    private constructor();
-    static getInstance(): AstroService;
-    usePathsFrom: <T, TParam extends string = "slug", TProps = T>(items: T[], options?: PathsOptions<T, TParam, TProps>) => AstroPath<TParam, TProps>[];
-    useGetStaticPaths: <TData = unknown, TParam extends string = "slug", TProps = CollectionEntryLike<TData>>(getCollectionFn: (collection: string) => Promise<CollectionEntryLike<TData>[]>, collectionName: string, options?: PathsOptions<CollectionEntryLike<TData>, TParam, TProps>) => Promise<AstroServiceResult<AstroPath<TParam, TProps>[]>>;
-    useFindEntry: <T>(items: T[], value: string, keyFrom?: (item: T) => string | number) => T | null;
-    useGeneratePagination: <T, TParam extends string = "page">(items: T[], pageSize?: number, param?: TParam) => AstroPath<TParam, PaginationProps<T>>[];
-    usePathsFromValues: <TParam extends string = "slug">(values: (string | number)[], param?: TParam) => AstroPath<TParam, string | number>[];
-    useExtractUniqueValues: <T, V>(items: T[], keyFrom: (item: T) => V | V[]) => V[];
-}
-export declare const usePathsFrom: <T, TParam extends string = "slug", TProps = T>(items: T[], options?: PathsOptions<T, TParam, TProps>) => AstroPath<TParam, TProps>[], useGetStaticPaths: <TData = unknown, TParam extends string = "slug", TProps = CollectionEntryLike<TData>>(getCollectionFn: (collection: string) => Promise<CollectionEntryLike<TData>[]>, collectionName: string, options?: PathsOptions<CollectionEntryLike<TData>, TParam, TProps>) => Promise<AstroServiceResult<AstroPath<TParam, TProps>[]>>, useFindEntry: <T>(items: T[], value: string, keyFrom?: ((item: T) => string | number) | undefined) => T | null, useGeneratePagination: <T, TParam extends string = "page">(items: T[], pageSize?: number, param?: TParam) => AstroPath<TParam, PaginationProps<T>>[], usePathsFromValues: <TParam extends string = "slug">(values: (string | number)[], param?: TParam) => AstroPath<TParam, string | number>[], useExtractUniqueValues: <T, V>(items: T[], keyFrom: (item: T) => V | V[]) => V[];
+export declare function useAstroPathsFrom<T, TParam extends string = "slug", TProps = T>(items: T[], options?: PathsOptions<T, TParam, TProps>): AstroPath<TParam, TProps>[];
+/**
+ * Fetch a collection and transform it into safe Astro paths.
+ * Returns a result object instead of throwing on error.
+ *
+ * @param getCollectionFn - Astro's getCollection function
+ * @param collectionName - Name of the collection to fetch
+ * @param options - Path generation options
+ * @returns Safe result with data or error
+ *
+ * @example
+ * ```ts
+ * export async function getStaticPaths() {
+ *   const result = await useAstroGetStaticPaths(getCollection, "blog");
+ *   if (result.ok) return result.data;
+ *   TODO: traer el useLogger('error', result.error)
+ *   console.error(result.error);
+ *   return [];
+ * }
+ * ```
+ */
+export declare function useAstroGetStaticPaths<TData = unknown, TParam extends string = "slug", TProps = CollectionEntryLike<TData>>(getCollectionFn: (collection: string) => Promise<CollectionEntryLike<TData>[]>, collectionName: string, options?: PathsOptions<CollectionEntryLike<TData>, TParam, TProps>): Promise<AstroServiceResult<AstroPath<TParam, TProps>[]>>;
+/**
+ * Find a collection entry by slug or custom key.
+ *
+ * @param items - Collection items to search
+ * @param value - Value to match (slug, id, etc.)
+ * @param keyFrom - Optional function to extract the key from an item
+ * @returns Matched item or null
+ *
+ * @example
+ * ```ts
+ * const posts = await getCollection("blog");
+ * const post = useAstroFindEntry(posts, "hello-world");
+ * if (post) console.log(post.data.title);
+ * ```
+ */
+export declare function useAstroFindEntry<T>(items: T[], value: string, keyFrom?: (item: T) => string | number): T | null;
+/**
+ * Generate paginated Astro paths from a list of items.
+ *
+ * @param items - Items to paginate
+ * @param pageSize - Number of items per page
+ * @param param - URL param name for page number
+ * @returns Array of Astro paths with pagination props
+ *
+ * @example
+ * ```ts
+ * const posts = await getCollection("blog");
+ * const pages = useAstroGeneratePagination(posts, 10);
+ * // [{ params: { page: undefined }, props: { items: [...], currentPage: 1, totalPages: 3 } },
+ * //  { params: { page: "2" }, props: { items: [...], currentPage: 2, totalPages: 3 } }, ...]
+ * ```
+ */
+export declare function useAstroGeneratePagination<T, TParam extends string = "page">(items: T[], pageSize?: number, param?: TParam): AstroPath<TParam, PaginationProps<T>>[];
+/**
+ * Convert simple values into Astro paths.
+ *
+ * @param values - Array of string or number values
+ * @param param - URL param name
+ * @returns Array of Astro paths
+ *
+ * @example
+ * ```ts
+ * const categories = ["tech", "design", "business"];
+ * const paths = useAstroPathsFromValues(categories, "category");
+ * // [{ params: { category: "tech" }, props: "tech" }, ...]
+ * ```
+ */
+export declare function useAstroPathsFromValues<TParam extends string = "slug">(values: (string | number)[], param?: TParam): AstroPath<TParam, string | number>[];
+/**
+ * Extract unique values from a collection, supporting single values or arrays.
+ *
+ * @param items - Collection items
+ * @param keyFrom - Function to extract value(s) from each item
+ * @returns Array of unique values
+ *
+ * @example
+ * ```ts
+ * const posts = [{ tags: ["ts", "react"] }, { tags: ["ts", "vue"] }];
+ * const tags = useAstroExtractUniqueValues(posts, (p) => p.tags);
+ * // ["ts", "react", "vue"]
+ * ```
+ */
+export declare function useAstroExtractUniqueValues<T, V>(items: T[], keyFrom: (item: T) => V | V[]): V[];
 //# sourceMappingURL=astro.service.d.ts.map

package/dist/adapters/astro/astro.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"astro.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/astro/astro.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,sBAAsB,CAAC;AAE9B;;;GAGG;AACH,qBAAa,YAAa,YAAW,aAAa;IACjD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IAEtC,OAAO,eAAiB;IAExB,OAAc,WAAW,IAAI,YAAY,CAKxC;IAEM,YAAY,GAAI,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,CAAC,SAC5D,CAAC,EAAE,YACD,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,KACtC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAkB5B;IAEK,iBAAiB,GACvB,KAAK,GAAG,OAAO,EACf,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,mBAElB,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC,kBAC9D,MAAM,YACb,YAAY,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,KAC/D,OAAO,CAAC,kBAAkB,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAoBzD;IAEK,YAAY,GAAI,CAAC,SAChB,CAAC,EAAE,SACH,MAAM,YACH,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,KACpC,CAAC,GAAG,IAAI,CAQT;IAEK,qBAAqB,GAAI,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM,SACzD,CAAC,EAAE,6BAEH,MAAM,KACX,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAgBxC;IAEK,kBAAkB,GAAI,MAAM,SAAS,MAAM,GAAG,MAAM,UAClD,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,UACpB,MAAM,KACX,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,CAKrC;IAEK,sBAAsB,GAAI,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,KAAG,CAAC,EAAE,CAGpF;CACF;AAGD,eAAO,MACN,YAAY,GA3GW,CAAC,EAAE,MAAM,SAAS,MAAM,WAAW,MAAM,6FA4GhE,iBAAiB,GApFhB,KAAK,YACL,MAAM,SAAS,MAAM,WACrB,MAAM,6DAEwB,MAAM,4DACpB,MAAM,mIAgFvB,YAAY,GAxDW,CAAC,qBAEhB,MAAM,0BACU,MAAM,GAAG,MAAM,4BAsDvC,qBAAqB,GA3CW,CAAC,EAAE,MAAM,SAAS,MAAM,sGA4CxD,kBAAkB,GAtBW,MAAM,SAAS,MAAM,mBACzC,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,2DAsB5B,sBAAsB,GAbW,CAAC,EAAE,CAAC,mDAcM,CAAC"}
+{"version":3,"file":"astro.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/astro/astro.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,CAAC,EAC9E,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,GAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAM,GAC3C,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAkB7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC3C,KAAK,GAAG,OAAO,EACf,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAEnC,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC,EAC9E,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,YAAY,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAM,GACpE,OAAO,CAAC,kBAAkB,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAe1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GACpC,CAAC,GAAG,IAAI,CAQV;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM,EAC3E,KAAK,EAAE,CAAC,EAAE,EACV,QAAQ,SAAK,EACb,KAAK,GAAE,MAAyB,GAC9B,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAYzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM,EACrE,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAC3B,KAAK,GAAE,MAAyB,GAC9B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,CAKtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,CAEhG"}