katanakit-js 2.1.5

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.4] - Unreleased
+
+Current development version. This is the first release published under the
+**`katanakit-js`** npm name (previous development releases were published as
+`katanakit-dev`).
+
+### Added
+
+- **Nuxt adapter** — new `katanakit-js/adapters/nuxt` subpath exporting three
+  pure helpers that bridge KatanaKit Safe Results to Nuxt/Nitro server routes:
+  `useUnwrap(result, context?)`, `useSafeResponse(result)` and
+  `useEventResponse(event, result)`. They avoid a hard dependency on `h3`
+  (which ships with Nuxt).
+- **Site config and SEO module** — new `src/config/` layer with
+  `siteConfig`/`SiteConfig` and pure SEO helpers (`useGenerateMetaTags`,
+  `useHeadTags`, `useTitle`, `useRssHeadLink`), re-exported from the main
+  barrel. Includes HTML/attribute escaping and JSON-LD breakout protection.
+- **`publish:*` scripts** — `publish:patch`, `publish:minor`, `publish:major`
+  and `publish:beta` (tagged `beta`) with a `prepublishOnly` gate that runs
+  Biome, tests and the build before publishing.
+- New Vitest suites for RSS, Nuxt and SEO services (57 tests across 7 files).
+
+### Changed
+
+- **Renamed the npm package** from `katanakit-dev` to **`katanakit-js`**
+  (version bumped to 2.1.4). The `exports` map now exposes the root entry plus
+  two framework subpaths: `katanakit-js/adapters/express` and
+  `katanakit-js/adapters/nuxt`.
+- **Restructured dependencies** — only `@js-temporal/polyfill` remains a
+  runtime dependency; `express`, `cors`, `dotenv` and `@prisma/orm-postgres`
+  are now **optional peer dependencies** installed only by consumers that use
+  the Express adapter or the Prisma layer.
+- Upgraded the toolchain: Biome to v2 (migrated `biome.json` schema), Vitest to
+  v5, TypeScript to v7; Node engine floor raised to `>=22.18.0`.
+- Hardened the Express reference adapter: CORS defaults to the comma-separated
+  `CORS_ORIGINS` allow-list (localhost fallback), `x-powered-by` is disabled
+  and JSON/urlencoded bodies are capped at 100 kb.
+
+### Fixed
+
+- **Pure ESM `.js` exports** — all relative imports in `src/` now use explicit
+  `.js` extensions (`module: nodenext`), so Node's ESM loader and bundlers
+  resolve the emitted `dist/` correctly.
+- **`WorkerService` pool correlation** — `useRunPool` now correlates responses
+  by echoing a `taskId` from the worker blob, fixing concurrent race
+  conditions.
+- **`useEncrypt` salt** — generates a random 128-bit salt when none is provided
+  instead of relying on a fixed default.
+- **SEO JSON-LD escaping** — `<`, `>` and `&` are escaped inside the
+  `application/ld+json` script to prevent `</script>` breakout.
+
+## [2.0.0] - 2026-09-03
+
+Developed and published as `katanakit-dev`.
+
+### Changed
+
+- **Reorganized the project with hexagonal architecture** into `types/`,
+  `core/services/` (ports + pure services), `infrastructure/` (browser/runtime
+  adapters), `adapters/` (Astro + Express) and `prisma/`, replacing the previous
+  flat `helpers/`/`api/` layout.
+- Exposed the public API through barrel files (`src/index.ts` and per-layer
+  `index.ts`).
+
+### Added
+
+- Added `biome.json` and `vitest.config.ts`; wired `typecheck`, `build`, `test`,
+  `lint`, `format` and `check` scripts.
+- Added Vitest unit tests for the HTTP client, logger, storage, geometry, errors
+  and reactive signals.
+- Added English documentation (`README.md`, `CONTRIBUTING.md`, `docs/`,
+  `SECURITY.md`).
+
+### Fixed
+
+- Fixed TypeScript compile errors: broken imports, broken singleton guards
+  (`TimingService` and `ViewportService`), the `FIND_ENTRY` scope bug in
+  `AstroService`, and Express `Request`/`Response` typing.
+- Removed all side effects on import (top-level `fetch` to dummyjson.com,
+  `console.log` calls, storage writes and timers).
+- Fixed the Express server: `listen` now uses the configured port/host, the user
+  router is mounted, and handler `(req, res)` argument order is correct.
+- Fixed the logger call sites (level is now the first argument of `useLog`).
+
+### Removed
+
+- Removed duplicate type definitions (unified in `src/types/`), dead code, empty
+  files and the broken signals draft.
+- Moved demos to `examples/` and dropped the obsolete `wiki/` documentation.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 senseikatana - Sergio Jurado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,446 @@
+# 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.
+
+## 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.
+
+## Installation
+
+```bash
+npm install katanakit-js
+# or
+bun add katanakit-js
+```
+
+Requirements: **Node.js >= 22.18.0** (pure ESM package). TypeScript consumers
+should use `moduleResolution: "nodenext"` (or `"bundler"`).
+
+### Framework adapters
+
+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";
+```
+
+`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
+
+```bash
+git clone https://github.com/senseikatana/katanakit.git
+cd katanakit
+bun install
+bun run build       # outputs to dist/
+```
+
+## Quick Start
+
+Everything below is importable from the main barrel `katanakit-js`.
+
+### HTTP client
+
+```ts
+import { useInit, useGet, usePost, useBuildUrl } from "katanakit-js";
+
+// 1. Register your APIs once.
+useInit({
+  pokeapi: {
+    baseUri: "https://pokeapi.co/api/v2",
+    endpoints: {
+      pokemonById: "/pokemon/:id/",
+      pokemons: "/pokemons/",
+    },
+  },
+});
+
+// 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", {
+  params: { id: 25 },
+});
+
+if (result.ok) {
+  console.log(result.data.name);
+} else {
+  console.error(result.error.message, result.error.status);
+}
+
+// 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).
+
+## RSS feeds for Astro
+
+`RssService` generates pure RSS 2.0 XML with **no external dependencies**
+(`@astrojs/rss` is not required).
+
+```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,
+    }));
+  },
+});
+```
+
+Add the feed `<link>` tag to your layout's `<head>`:
+
+```astro
+---
+import { useRssLinkTag } from "katanakit-js";
+---
+<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 },
+  ],
+};
+```
+
+Then inject complete meta tags (title, description, canonical, Open Graph,
+Twitter Card and JSON-LD) in your layout:
+
+```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>
+```
+
+The RSS endpoint consumes the same config:
+
+```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,
+  }));
+});
+```
+
+## 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/" },
+  },
+});
+```
+
+```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
+});
+```
+
+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).
+
+## 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.
+
+## 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.
+
+## License
+
+[MIT](LICENSE)

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

@@ -0,0 +1,18 @@
+import type { AstroPath, AstroServiceResult, CollectionEntryLike, IAstroService, 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.
+ */
+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[];
+//# sourceMappingURL=astro.service.d.ts.map

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

@@ -0,0 +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"}

package/dist/adapters/astro/astro.service.js

@@ -0,0 +1,83 @@
+/**
+ * Astro adapter (Facade + Adapter + Singleton). Converts arbitrary collections
+ * into the `getStaticPaths` format Astro expects, wrapped in a Safe Result.
+ */
+export class AstroService {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!AstroService.instance) {
+            AstroService.instance = new AstroService();
+        }
+        return AstroService.instance;
+    }
+    usePathsFrom = (items, options = {}) => {
+        const { param = "slug", valueFrom = (item) => {
+            const record = item;
+            return record?.slug ?? record?.id ?? "";
+        }, propsFrom = (item) => item, paramsFrom, } = options;
+        return items.map((item) => ({
+            params: (paramsFrom ? paramsFrom(item) : { [param]: String(valueFrom(item)) }),
+            props: propsFrom(item),
+        }));
+    };
+    useGetStaticPaths = async (getCollectionFn, collectionName, options = {}) => {
+        try {
+            const entries = await getCollectionFn(collectionName);
+            const paths = this.usePathsFrom(entries, options);
+            return {
+                data: paths,
+                error: null,
+                ok: true,
+            };
+        }
+        catch (error) {
+            return {
+                data: null,
+                error: {
+                    message: `Error generating routes for collection "${collectionName}"`,
+                    collectionName,
+                    details: error instanceof Error ? error.message : String(error),
+                },
+                ok: false,
+            };
+        }
+    };
+    useFindEntry = (items, value, keyFrom) => {
+        const getKey = keyFrom ??
+            ((item) => {
+                const record = item;
+                return record?.slug ?? record?.id ?? "";
+            });
+        return items.find((item) => String(getKey(item)) === value) ?? null;
+    };
+    useGeneratePagination = (items, pageSize = 10, param = "page") => {
+        const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
+        return Array.from({ length: totalPages }, (_, i) => {
+            const currentPage = i + 1;
+            return {
+                params: {
+                    [param]: currentPage === 1 ? undefined : String(currentPage),
+                },
+                props: {
+                    items: items.slice(i * pageSize, (i + 1) * pageSize),
+                    currentPage,
+                    totalPages,
+                },
+            };
+        });
+    };
+    usePathsFromValues = (values, param = "slug") => {
+        return values.map((value) => ({
+            params: { [param]: String(value) },
+            props: value,
+        }));
+    };
+    useExtractUniqueValues = (items, keyFrom) => {
+        const values = items.flatMap(keyFrom);
+        return [...new Set(values)];
+    };
+}
+// Singleton instance and destructured exports.
+export const { usePathsFrom, useGetStaticPaths, useFindEntry, useGeneratePagination, usePathsFromValues, useExtractUniqueValues, } = AstroService.getInstance();
+//# sourceMappingURL=astro.service.js.map

package/dist/adapters/astro/astro.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"astro.service.js","sourceRoot":"","sources":["../../../src/adapters/astro/astro.service.ts"],"names":[],"mappings":"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"}