@liturgical-calendar/components-js
Version:
Liturgical calendar components for javascript: an html select populated with liturgical calendars supported by the Liturgical Calendar API; form controls for parameters that are supported by the Liturgical Calendar API; a webcalendar; and liturgy of the d
212 lines • 10.7 kB
TypeScript
/**
* A client for interacting with the Liturgical Calendar API.
* This class provides methods to fetch and manage liturgical calendar data,
* including the General Roman Calendar, National Calendars, and Diocesan Calendars.
*
* @class
* @description The ApiClient handles all API interactions for retrieving liturgical calendar data.
* It supports fetching calendar metadata, managing calendar settings, and retrieving specific calendar types
* (General Roman, National, or Diocesan). The class maintains internal state for calendar data and request parameters,
* and provides methods to listen to UI component changes.
*
* @example
* const client = new ApiClient();
* // Initialize with default API URL
* await ApiClient.init();
* // Fetch General Roman Calendar
* const calendarData = await client.fetchCalendar();
*
* @example
* // Fetch a National Calendar
* const client = new ApiClient();
* const nationalCalendarData = client.fetchNationalCalendar('IT').then( data => {
* // Handle the response data
* });
*/
export default class ApiClient {
/**
* @type {string}
* @private
* @static
* @default 'https://litcal.johnromanodorazio.com/api/dev'
*/
private static "__#15@#apiUrl";
/**
* @type {{calendars: '/calendars', calendar: '/calendar', events: '/events', easter: '/easter', decrees: '/decrees', data: '/data', missals: '/missals', tests: '/tests', schemas: '/schemas'}}
* @private
* @constant
*/
private static "__#15@#paths";
/**
* @type {import('../typedefs.js').CalendarMetadata | null}
* @private
* @static
* Response object from the API /calendars path
*/
private static "__#15@#metadata";
/**
* Cache for calendar data, keyed by a combination of calendar parameters.
* This allows reusing previously fetched data when the same parameters are requested.
* @type {Map<string, {data: object, timestamp: number}>}
* @private
* @static
*/
private static "__#15@#calendarCache";
/**
* Initializes the ApiClient with an optional API URL.
* If a URL is provided, it sets the internal API URL to the given value.
* Then, it fetches the available liturgical calendars from the API.
*
* @param {string|null} url - Optional API URL to override the default URL.
* @returns {Promise<ApiClient|boolean>} A promise that resolves to an `ApiClient` instance when the calendar metadata has been fetched, or `false` if an error occurs.
* @static
*/
static init(url?: string | null): Promise<ApiClient | boolean>;
/**
* Fetches metadata about available liturgical calendars from the API.
*
* This method sends a GET request to the API endpoint for calendars metadata when the `#metadata` property is null, and processes the response.
* If the request is successful, it extracts the `litcal_metadata` from the response data
* and assigns it to the `#metadata` property of the `ApiClient` class.
* If the `#metadata` property is not null, it returns a resolved promise with the `ApiClient` instance.
* This way, if the static init method is called more than once, initialization is only performed once, and only one fetch request is made to the API.
*
* @returns {Promise<ApiClient|boolean>} A promise that resolves to an `ApiClient` instance if the request is successful, or `false` if an error occurs.
*/
static "__#15@#fetchCalendars"(): Promise<ApiClient | boolean>;
/**
* Clears all cached calendar data.
* Useful when you want to force fresh data from the API.
* @static
*/
static clearCache(): void;
/**
* This static getter provides access to the metadata object that contains information
* about the available liturgical calendars, including national and diocesan calendars.
* The metadata is initially fetched from the API during the client initialization.
*
* @returns {import('../typedefs.js').CalendarMetadata} An object containing the metadata of the liturgical calendars.
*/
static get _metadata(): import("../typedefs.js").CalendarMetadata;
/**
* Static getter provides access to the internal API URL
* used by the ApiClient to make requests to the liturgical calendar API.
*
* @returns {string} The API URL.
*/
static get _apiUrl(): string;
/**
* Refetches calendar data based on the current category and calendar ID.
*
* This method determines the current category of the calendar (national, diocesan, or general)
* and fetches the corresponding calendar data. It logs the fetched calendar type and the
* calendar data to the console once the data is retrieved.
*
* If the current category is 'national', it fetches the national calendar using the current
* calendar ID. If the category is 'diocesan', it fetches the diocesan calendar. For any other
* category, it fetches the General Roman Calendar.
*/
refetchCalendarData(): void;
/**
* Fetches the General Roman Calendar data from the API for a given year.
*
* @param {string|null} locale The locale for the General Roman Calendar. If null, the default or last set locale is used.
*
* This method sends a POST request to the calendar endpoint with the configured parameters.
* The year parameter is extracted from the request body and placed in the URL path.
* The remaining parameters are sent in the request body as JSON.
*
* If the same calendar with identical parameters was previously fetched, the cached data
* is returned without making a new API request.
*/
fetchCalendar(locale?: string | null): void;
/**
* Fetches a national liturgical calendar from the API
* @param {string} calendar_id - The identifier for the national calendar to fetch
* @param {string} [locale] - The locale for the national calendar
* @throws {Error} When network request fails
* @description This method fetches a national liturgical calendar by its ID, and optionally a supported locale. It extracts the year from params
* to use in the URL path and sends other relevant parameters in the request body. Parameters that determine the dates for
* epiphany, ascension, corpus_christi, eternal_high_priest are excluded from the request parameters,
* as these options are built into the National calendar being requested.
*
* If the same calendar with identical parameters was previously fetched, the cached data
* is returned without making a new API request.
*/
fetchNationalCalendar(calendar_id: string, locale?: string): void;
/**
* Fetches a diocesan liturgical calendar from the API
* @param {string} calendar_id - The identifier for the diocesan calendar to fetch
* @param {string} [locale] - The locale for the diocesan calendar
* @throws {Error} When network request fails
* @description This method fetches a diocesan liturgical calendar by its ID, and optionally a supported locale. It extracts the year from params
* to use in the URL path and sends other relevant parameters in the request body. Parameters that determine the dates for
* epiphany, ascension, corpus_christi, eternal_high_priest are excluded from the request parameters,
* as these options are built into the Diocesan calendar being requested.
*
* If the same calendar with identical parameters was previously fetched, the cached data
* is returned without making a new API request.
*/
fetchDiocesanCalendar(calendar_id: string, locale?: string): void;
listenTo(uiComponent?: null): ApiClient | undefined;
/**
* Set the year for which the calendar is to be retrieved.
* @param {number} yearValue - The year for which to retrieve the calendar. Must be a number and be between 1970 and 9999.
* @throws {Error} If no year is given, or if the year is not a number, or if the year is not between 1970 and 9999.
* @returns {ApiClient} The current instance for method chaining.
*/
year(yearValue: number): ApiClient;
/**
* Set the type of the year for which the calendar is to be retrieved.
* @param {YearType} yearTypeValue - The type of the year for which to retrieve the calendar. Must be either LITURGICAL or CIVIL.
* @throws {Error} If no year_type is given, or if the year_type is not either LITURGICAL or CIVIL.
* @returns {ApiClient} The current instance for method chaining.
*/
yearType(yearTypeValue: YearType): ApiClient;
/**
* @deprecated Use year() instead. This method will be removed in a future version.
* @param {number} year - The year for which to retrieve the calendar.
* @returns {ApiClient} The current instance for method chaining.
*/
setYear(year: number): ApiClient;
/**
* @deprecated Use yearType() instead. This method will be removed in a future version.
* @param {YearType} year_type - The type of the year.
* @returns {ApiClient} The current instance for method chaining.
*/
setYearType(year_type: YearType): ApiClient;
/**
* The metadata object that contains information about the available liturgical
* calendars, including national and diocesan calendars.
* The metadata is initially fetched from the API during static ApiClient initialization.
*
* @type {import('../typedefs.js').CalendarMetadata}
*/
get _metadata(): import("../typedefs.js").CalendarMetadata;
/**
* The internal API URL used by the ApiClient to make requests to the liturgical calendar API.
*
* @returns {string} The API URL.
*/
get _apiUrl(): string;
/**
* @returns {import('../typedefs.js').CalendarData} The currently cached calendar data.
* This property can be used to retrieve the current liturgical calendar data.
* Note that the data is only available after `fetchCalendar()`, `fetchNationalCalendar()`,
* or `fetchDiocesanCalendar()` has been called.
*/
get _calendarData(): import("../typedefs.js").CalendarData;
/**
* The event bus that can be used to subscribe to events emitted by the ApiClient.
*
* The event bus emits events of type `calendarFetched` when a new calendar is fetched
* from the API. The event detail is an object of type `CalendarData` containing the
* liturgical events of the fetched calendar.
* @type {EventEmitter}
*/
get _eventBus(): EventEmitter;
#private;
}
import { YearType } from '../Enums.js';
import EventEmitter from './EventEmitter.js';
//# sourceMappingURL=ApiClient.d.ts.map