Project Structure

Project Structure

A map of src/ and where to find things. The design rationale is on the Architecture page.

← Back to Home

Top level

src/
├── index.ts            # Public entry point — re-exports the whole API
├── setupTests.ts       # Vitest global setup (exposes SUPPORT_PATH / FEEDS_PATH)
├── himalaya.d.ts       # Ambient types for himalaya (ships no types)
├── rss/                # Feed parsing pipeline
└── component/          # HTML → component pipeline

rss/ — feed pipeline

rss/
├── RSSFeed.ts          # The RSSFeed class: validate() and build()
├── RSS.ts              # Typed RSS / Channel / Item / media interfaces
├── Tag.ts              # Required-tag & valid-tag allow-lists (rss / channel / item)
├── Attributes.ts       # Attribute helpers for fast-xml-parser output
└── RSSFeed.test.ts     # Feed parsing/validation tests

component/ — HTML pipeline

component/
├── HTMLMapper.ts           # Public entry: toComponents(), getRootElement(), pre-processing
├── HTMLMapper.test.ts
├── Component.ts            # ComponentType/TextType unions, interfaces, is* guards
├── Component.test.ts
├── mapping/
│   ├── Mapping.ts          # reduceComponents reducer + recursive detection engine
│   ├── Mapping.schema.ts   # Zod schemas: Params, Mapping, filters, component mappings
│   ├── Mapping.constants.ts# Tag/attribute allow-lists
│   ├── Mapping.utils.ts    # Leaf helpers (sanitizeNode, matchesPattern, processTextLinks…)
│   ├── Mapping.embeds.ts   # Social-embed converters/detectors (Instagram, TikTok, YouTube…)
│   └── Mapping.test.ts
├── node/
│   ├── Node.ts             # himalaya AST node types + helpers (getAttributes, findDescendants, SetUtils)
│   └── Node.test.ts
└── schema/
    ├── Schema.ts           # Zod schemas for recipe (JSON-LD) extraction
    └── Schema.test.ts

The component/ sources are grouped into per-concern folders (mapping/, node/, schema/) with their tests colocated. Mapping.ts holds the recursive detection engine; its leaf concerns are extracted into the sibling Mapping.* modules and re-exported so the public API is unchanged.

Test fixtures

Real RSS feeds and HTML snippets live under src/support/ (feeds/ and html/). setupTests.ts exposes process.env.SUPPORT_PATH and process.env.FEEDS_PATH so tests read fixtures without hardcoded paths. See Testing.

Build output

npm run build (vp pack) compiles src/index.ts into dist/ as unbundled ESM modules plus .d.mts declarations (configured under the pack key in vite.config.ts). Only dist/ is published.

Naming conventions

• Public classes are RSSFeed and HTMLMapper.
• Mapping internals are grouped under component/mapping/ with a Mapping.<concern>.ts name.
• Type guards are is<Type>Component (e.g. isImageComponent), defined in Component.ts.
• Tests are colocated as *.test.ts next to the file they cover.