How nazmul-nhb/chronos-date works
1. Repository shape
- This repo is split into two major surfaces: a published TypeScript date-time library under src/, and a Next.js documentation site under docs/.
- The library is the product; the docs app is both marketing/docs and an interactive reference surface for the library.
2. Core library boundary
- src/index.ts is the main package entry, with additional subpath exports implied by the README (/guards, /utils, /types, /constants, /plugins).
- The library is designed for tree-shakeable imports and framework-agnostic usage across Node, browser, Deno, and Bun.
3. Primary runtime model
- src/core/Chronos.ts and src/core/chronos-fn.ts define the main runtime abstraction: an immutable date-time wrapper plus a function-style convenience wrapper.
- The Chronos API is the central orchestrator; higher-level operations like formatting, comparison, parsing, and manipulation are built on top of it.
4. Supporting utility layer
- src/utils/ holds reusable date logic split into concerns such as calculation, comparison, formatting, parsing, and generic helpers.
- These utilities are the shared dependency surface used by the core class, plugins, guards, and type utilities rather than being directly exposed as a monolith.
5. Plugin architecture
- src/plugins/ contains the extension modules that add domain-specific behavior, such as timezone, season, zodiac, business rules, greeting/day-part logic, relative time, and rounding.
- The README’s Chronos.use(plugin) model indicates a global/plugin-registration boundary: plugins extend the core Chronos capability set without changing the base API.
6. Validation, constants, and types
- src/guards.ts, src/constants/, and src/types/ form the library’s “static” support layer.
- Guards provide runtime validation, constants encode reusable calendrical/domain data, and types define the public TypeScript contract for inputs, formats, plugin extensions, and Chronos-specific shapes.
7. Documentation source of truth
- The docs content lives in docs/content/docs/** as MDX pages organized by feature area: Chronos API, plugins, guards, utils, installation, quick start, and changelog.
- Many sections have meta.json files, suggesting a structured content model used to drive navigation and page generation.
8. Docs application layer
- docs/app/ is a Next.js App Router site that renders the content tree, with routes for the home page, docs pages, and several special outputs.
- docs/app/docs/[[...slug]]/page.tsx is the main documentation page renderer, while docs/app/layout.tsx and docs/app/global.css define the site shell and styling.
9. Docs tooling and generated metadata
- docs/lib/ contains source integration code and generated artifacts such as .generated-modules.ts, .generated-types.json, and a cache file, indicating a build-time content/type generation step.
- docs/source.config.ts likely defines how MDX content is discovered and transformed into these generated docs primitives.
10. Interactive docs features
- The docs site includes specialized UI components for code copy, tabs, accordion/collapsible panels, markdown rendering, playgrounds, and AI/search experiences.
- docs/app/api/search/route.ts and docs/app/api/chat/route.ts expose server-side endpoints for search and assistant-style interactions within the documentation experience.
11. Machine-readable and shareable documentation outputs
- The docs app includes llms.txt, llms.mdx, llms-full.txt, and a docs-specific llms.mdx/docs/... route, which indicates deliberate support for LLM-readable documentation exports.
- There is also Open Graph image generation under docs/app/opengraph-image.tsx and docs/app/og/**, supporting social/link previews.
12. Build, release, and repository automation
- tsdown.config.ts, biome.json, and the root package.json suggest a TypeScript-first build and lint/format toolchain for the library package.
- GitHub Actions (.github/workflows/publish.yml) handle publishing, while scripts/ contains repository automation such as changelog generation, copying static chronos assets into docs, and pulling mainline changes.
- Husky pre-commit hooks and link validation scripts indicate the repo treats documentation correctness and package release quality as part of the architecture, not an afterthought.
Main entry points: app Docs app · index.ts Entry · Chronos.ts Chronos · guards.ts Static support
Components 19
Library
Published Chronos date-time package and its internal runtime layers.
- Entry · Main public exports for the Chronos library.
src/index.ts - Chronos · Immutable date-time wrapper and main orchestration API.
src/core/Chronos.ts - Wrapper fn · Function-style convenience wrapper around the Chronos runtime.
src/core/chronos-fn.ts - Utils · Reusable date calculation, comparison, formatting, parsing, and helper logic.
src/utils/index.ts - Plugins · Domain plugins that extend Chronos via registration.
src/plugins - Static support · Runtime guards, calendrical constants, and public TypeScript contracts.
src/guards.ts - Constants · Reusable basic, season, and timezone constants.
src/constants/index.ts - Types · Chronos and plugin-related TypeScript shapes.
src/types/index.ts
Docs site
Next.js documentation app, content, and interactive tooling.
- Content tree · Structured MDX documentation source organized by feature area.
docs/content/docs - Docs app · App Router site that renders docs pages and special outputs.
docs/app - Doc page · Main documentation page renderer for slugs.
docs/app/docs/[[...slug]]/page.tsx - Site shell · Global app layout and styling for the docs site.
docs/app/layout.tsx - AI/search API · Documentation search and chat endpoints.
docs/app/api - LLM outputs · LLMs.txt, LLMs.mdx, and full text documentation exports.
docs/app/llms.txt - Open Graph · Social preview image generation for docs pages.
docs/app/opengraph-image.tsx - UI components · Reusable docs widgets for markdown, tabs, copy, playgrounds, and AI surfaces.
docs/components - Docs lib · Content integration, generated metadata, and shared docs utilities.
docs/lib
Automation
Repository scripts and release workflows.
- Package · Workspace and package metadata for the repository.
package.json - Build & release · TypeScript build, linting, publishing, and repository scripts.
tsdown.config.ts
Connections 23
- Package → Entry: packages · Defines the published package surface.
- Package → Docs app: workspace · Hosts the documentation application alongside the library.
- Entry → Chronos: exports · Re-exports the main Chronos runtime.
- Entry → Wrapper fn: exports · Exposes the convenience wrapper API.
- Chronos → Utils: uses · Delegates date math, parsing, comparison, and formatting.
- Chronos → Static support: uses · Relies on guards, constants, and shared types.
- Wrapper fn → Chronos: wraps · Provides a function-style entry over the class runtime.
- Plugins → Chronos: extends · Plugins register behavior onto the core API.
- Plugins → Utils: depends on · Plugin logic reuses shared utility functions.
- Static support → Constants: includes · Static domain data used across the package.
- Static support → Types: defines · Public input and extension contracts.
- Docs app → Doc page: renders · Main docs route renders content pages.
- Docs app → Site shell: shell · Provides the site layout and global styling.
- Docs app → AI/search API: serves · Exposes search and chat endpoints.
- Docs app → LLM outputs: exports · Serves machine-readable documentation outputs.
- Docs app → Open Graph: generates · Creates social preview images.
- Doc page → Content tree: reads · Loads MDX docs by slug and section.
- Docs app → UI components: uses · Composes the interactive docs UI.
- Docs app → Docs lib: depends on · Uses generated metadata and shared docs helpers.
- Docs lib → Content tree: indexes · Transforms MDX content into navigable docs primitives.
- Docs lib → Entry: references · Docs examples and generated data point at the library API.
- Build & release → Entry: builds · TypeScript build and publish flow target the library package.
- Build & release → Docs app: maintains · Scripts support docs generation, changelog updates, and content sync.