legal-markdown-js
Version:
Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version
189 lines • 6.86 kB
TypeScript
/**
* @fileoverview Advanced Date Helpers - Node.js Extensions
*
* This module provides advanced date manipulation and formatting utilities
* that extend beyond the basic functionality of the original Ruby legal-markdown.
* These are Node.js specific enhancements for complex date operations.
*
* Features (Node.js extensions):
* - Date arithmetic (add years, months, days)
* - Advanced date formatting with multiple format options
* - Legal-specific date formats (formal, ordinal, etc.)
* - Complex date parsing and manipulation
* - Comprehensive error handling for edge cases
*
* @example
* ```typescript
* import { addYears, formatDate, DateFormats } from '../helpers/index.js';
*
* // Advanced date arithmetic
* const expiryDate = addYears('2025-01-01', 5);
*
* // Legal document formatting
* const legalDate = formatDate(new Date(), DateFormats.LEGAL);
* // Result: "16th day of July, 2025"
* ```
*/
/**
* Adds a specified number of years to a date
*
* This function handles both Date objects and ISO date strings, making it
* useful for contract calculations and legal document date processing.
*
* @param {Date | string} date - The base date as a Date object or ISO string
* @param {number} years - The number of years to add (can be negative)
* @returns {Date} A new Date object with the years added
* @throws {Error} If the input date is invalid
*
* @example
* ```typescript
* // Add 5 years to a contract start date
* const startDate = new Date('2025-01-01');
* const endDate = addYears(startDate, 5);
* // Result: Date object for 2030-01-01
*
* // Using with string input
* const futureDate = addYears('2025-07-16', 2);
* // Result: Date object for 2027-07-16
*
* // Subtract years (negative input)
* const pastDate = addYears(new Date(), -3);
* ```
*/
export declare function addYears(date: Date | string, years: number): Date;
/**
* Adds a specified number of days to a date
*
* Useful for calculating deadlines, notice periods, and other time-sensitive
* legal obligations in documents.
*
* @param {Date | string} date - The base date as a Date object or ISO string
* @param {number} days - The number of days to add (can be negative)
* @returns {Date} A new Date object with the days added
* @throws {Error} If the input date is invalid
*
* @example
* ```typescript
* // Add 30 days for a notice period
* const noticeDate = addDays(new Date(), 30);
*
* // Calculate a deadline
* const deadline = addDays('2025-07-16', 14);
*
* // Previous dates (negative input)
* const pastDate = addDays(new Date(), -7);
* ```
*/
export declare function addDays(date: Date | string, days: number): Date;
/**
* Adds a specified number of months to a date
*
* Handles month boundaries intelligently, useful for calculating quarterly
* reports, monthly payments, and other periodic legal obligations.
*
* @param {Date | string} date - The base date as a Date object or ISO string
* @param {number} months - The number of months to add (can be negative)
* @returns {Date} A new Date object with the months added
* @throws {Error} If the input date is invalid
*
* @example
* ```typescript
* // Add 6 months for a review period
* const reviewDate = addMonths(new Date('2025-01-31'), 6);
* // Result: Date object for 2025-07-31
*
* // Calculate quarterly dates
* const quarterlyDate = addMonths('2025-01-01', 3);
* // Result: Date object for 2025-04-01
*
* // Previous months (negative input)
* const previousQuarter = addMonths(new Date(), -3);
* ```
*/
export declare function addMonths(date: Date | string, months: number): Date;
/**
* Formats a date using advanced format strings
*
* Provides flexible date formatting with support for multiple format tokens.
* Particularly useful for legal documents that require specific date formats.
*
* @param {Date | string} date - The date to format
* @param {string} format - Format string with tokens (default: 'YYYY-MM-DD')
* @returns {string} The formatted date string
* @throws {Error} If the input date is invalid
*
* Supported format tokens:
* - YYYY: 4-digit year (2025)
* - YY: 2-digit year (25)
* - MMMM: Full month name (July)
* - MMM: Short month name (Jul)
* - MM: 2-digit month (07)
* - M: Month without leading zero (7)
* - DD: 2-digit day (16)
* - D: Day without leading zero (16)
* - Do: Day with ordinal suffix (16th)
* - dddd: Full day name (Wednesday)
* - ddd: Short day name (Wed)
*
* @example
* ```typescript
* const date = new Date('2025-07-16');
*
* formatDate(date, 'YYYY-MM-DD'); // "2025-07-16"
* formatDate(date, 'MM/DD/YYYY'); // "07/16/2025"
* formatDate(date, 'DD/MM/YYYY'); // "16/07/2025"
* formatDate(date, 'MMMM D, YYYY'); // "July 16, 2025"
* formatDate(date, 'dddd, MMMM Do, YYYY'); // "Wednesday, July 16th, 2025"
* formatDate(date, DateFormats.LEGAL); // "16th day of July, 2025"
* formatDate(date, DateFormats.FORMAL); // "Wednesday, July 16th, 2025"
*
* // Custom formats
* formatDate(date, 'MMMM Do, YYYY'); // "July 16th, 2025"
* ```
*/
export declare function formatDate(date: Date | string, format?: string, locale?: string): string;
/**
* Predefined date formats for common legal document use cases
*
* These formats provide standardized date formatting for different types
* of legal documents and jurisdictions.
*
* {Object} DateFormats
* @example
* ```typescript
* import { formatDate, DateFormats } from './advanced-date-helpers.js';
*
* const date = new Date('2025-07-16');
*
* formatDate(date, DateFormats.LEGAL); // "16th day of July, 2025"
* formatDate(date, DateFormats.FORMAL); // "Wednesday, July 16th, 2025"
* formatDate(date, DateFormats.US); // "07/16/2025"
* formatDate(date, DateFormats.EU); // "16/07/2025"
* formatDate(date, DateFormats.ISO); // "2025-07-16"
* formatDate(date, DateFormats.LONG); // "July 16, 2025"
* formatDate(date, DateFormats.SHORT); // "Jul 16, 2025"
* ```
*/
export declare const DateFormats: {
/** Legal format: "16th day of July, 2025" */
readonly LEGAL: "Do day of MMMM, YYYY";
/** Formal format: "Wednesday, July 16th, 2025" */
readonly FORMAL: "dddd, MMMM Do, YYYY";
/** Spanish format: "16 de julio de 2025" */
readonly SPANISH: "D de MMMM_ES de YYYY";
/** US format: "07/16/2025" */
readonly US: "MM/DD/YYYY";
/** European format: "16/07/2025" */
readonly EU: "DD/MM/YYYY";
/** ISO format: "2025-07-16" */
readonly ISO: "YYYY-MM-DD";
/** Long format: "July 16, 2025" */
readonly LONG: "MMMM D, YYYY";
/** Short format: "Jul 16, 2025" */
readonly SHORT: "MMM D, YYYY";
/** Year only: "2025" */
readonly YEAR: "YYYY";
/** Month and year: "July 2025" */
readonly MONTH_YEAR: "MMMM YYYY";
};
//# sourceMappingURL=advanced-date-helpers.d.ts.map