@artesa/feathers-open-holidays

FeathersJS services for the OpenHolidays API, powered by open-holiday-js.

Install

pnpm add @artesa/feathers-open-holidays

Peer dependencies:

pnpm add @feathersjs/feathers @feathersjs/errors

Usage

Register the services you need on your Feathers app:

import { feathers } from '@feathersjs/feathers'
import {
  CountriesService,
  LanguagesService,
  SubdivisionsService,
  PublicHolidaysService,
  SchoolHolidaysService,
} from '@artesa/feathers-open-holidays'

const app = feathers()

app.use('countries', new CountriesService())
app.use('languages', new LanguagesService())
app.use('subdivisions', new SubdivisionsService())
app.use('public-holidays', new PublicHolidaysService())
app.use('school-holidays', new SchoolHolidaysService())

All services accept an optional { url?: string } to override the API base URL:

app.use('countries', new CountriesService({ url: 'https://custom-api.example.com' }))

Services

CountriesService

// Find all countries
await app.service('countries').find()

// Filter by language
await app.service('countries').find({ query: { language: 'DE' } })

// Get a single country by ISO code
await app.service('countries').get('DE')

LanguagesService

await app.service('languages').find()
await app.service('languages').get('EN')

SubdivisionsService

Requires country in the query.

await app.service('subdivisions').find({ query: { country: 'DE' } })
await app.service('subdivisions').get('DE-BY', { query: { country: 'DE' } })

PublicHolidaysService

Requires country, startDate, and endDate in the query.

await app.service('public-holidays').find({
  query: {
    country: 'DE',
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    subdivision: 'DE-BY', // optional
    language: 'EN',       // optional
  },
})

await app.service('public-holidays').get('christmas', {
  query: { country: 'DE', startDate: '2024-01-01', endDate: '2024-12-31' },
})

SchoolHolidaysService

Same interface as PublicHolidaysService.

await app.service('school-holidays').find({
  query: {
    country: 'DE',
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    subdivision: 'DE-BY',
  },
})

Query Operators

All services support standard FeathersJS query operators:

Operator	Description	Example
$limit	Limit number of results	{ $limit: 5 }
$skip	Skip N results	{ $skip: 10 }
$sort	Sort by field (1 asc, -1 desc)	{ $sort: { isoCode: 1 } }
$select	Pick specific fields	{ $select: ['isoCode', 'name'] }

await app.service('countries').find({
  query: {
    language: 'EN',
    $sort: { isoCode: 1 },
    $limit: 10,
    $select: ['isoCode', 'name'],
  },
})

Development

pnpm install
pnpm test
pnpm build

License

MIT