@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.20

package/skills/iso-fns/references/api_reference.md

@@ -0,0 +1,435 @@
+# iso-fns API Reference
+
+## Table of Contents
+
+- [Types](#types)
+- [Common Options](#common-options)
+- [dateFns](#datefns)
+- [timeFns](#timefns)
+- [dateTimeFns](#datetimefns)
+- [instantFns](#instantfns)
+- [zonedDateTimeFns](#zoneddatetimefns)
+- [yearMonthFns](#yearmonthfns)
+- [monthDayFns](#monthdayfns)
+- [durationFns](#durationfns)
+- [Chaining](#chaining)
+- [Format Patterns](#format-patterns)
+
+## Types
+
+All types are ISO 8601 string representations in the `Iso` namespace:
+
+| Type | Format | Example |
+|------|--------|---------|
+| `Iso.Instant` | `YYYY-MM-DDThh:mm:ss.sssZ` | `'1970-01-01T00:00:00.000Z'` |
+| `Iso.ZonedDateTime` | `YYYY-MM-DDThh:mm:ss.sss+00:00[TimeZone]` | `'2024-01-15T09:30:00.000-06:00[America/Chicago]'` |
+| `Iso.DateTime` | `YYYY-MM-DDThh:mm:ss.sss` | `'2024-01-15T09:30:00.000'` |
+| `Iso.Date` | `YYYY-MM-DD` | `'2024-01-15'` |
+| `Iso.Time` | `hh:mm:ss.sss` | `'09:30:00.000'` |
+| `Iso.YearMonth` | `YYYY-MM` | `'2024-01'` |
+| `Iso.MonthDay` | `--MM-DD` | `'--01-15'` |
+| `Iso.Duration` | `PnYnMnDTnHnMnS` | `'P1Y2M3DT4H5M6S'` |
+
+## Common Options
+
+```ts
+type TemporalRoundingMode = 'halfExpand' | 'ceil' | 'trunc' | 'floor'
+type TemporalOverflow = 'constrain' | 'reject'
+type TemporalDisambiguation = 'compatible' | 'earlier' | 'later' | 'reject'
+type TemporalOffset = 'prefer' | 'ignore' | 'reject' | 'use'
+type TemporalSingularUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
+type TemporalPluralUnit = 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds'
+```
+
+Duration-like objects can be passed wherever `Iso.Duration` is accepted:
+```ts
+{ years?: number, months?: number, weeks?: number, days?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number }
+```
+
+## dateFns
+
+```ts
+now(timeZone?: string): Iso.Date
+fromNumbers(year: number, month: number, day: number): Iso.Date
+isValid(date: unknown): date is Iso.Date
+assertIsValid(date: unknown): asserts date is Iso.Date
+
+// Getters
+getYear(date): number
+getMonth(date): number
+getDay(date): number
+getDayOfWeek(date): number        // 1=Mon, 7=Sun
+getDayOfYear(date): number
+getWeekOfYear(date): number
+getDaysInMonth(date): number
+getDaysInYear(date): number
+inLeapYear(date): boolean
+getFields(date): { year, month, day }
+
+// Mutation (returns new value)
+with(date, { year?, month?, day? }, options?): Iso.Date
+add(date, durationLike, options?): Iso.Date
+subtract(date, durationLike, options?): Iso.Date
+
+// Comparison
+until(date, other, options?): Iso.Duration
+since(date, other, options?): Iso.Duration
+equals(date, other): boolean
+isEqual(date, other): boolean     // alias for equals
+isBefore(date, other): boolean
+isAfter(date, other): boolean
+isEqualOrBefore(date, other): boolean
+isEqualOrAfter(date, other): boolean
+compare(one, two): number
+
+// Conversion
+toDateTime(date, time?: Iso.Time): Iso.DateTime
+toZonedDateTime(date, { timeZone, time? } | timeZone): Iso.ZonedDateTime
+toYearMonth(date): Iso.YearMonth
+toMonthDay(date): Iso.MonthDay
+
+// Formatting
+format(date, formatString): string
+from(item): Iso.Date
+chain(date): IDateChain
+```
+
+## timeFns
+
+```ts
+now(timeZone?: string): Iso.Time
+fromNumbers(hour?, minute?, second?, millisecond?): Iso.Time
+isValid(time: unknown): time is Iso.Time
+assertIsValid(time: unknown): asserts time is Iso.Time
+
+// Getters
+getHour(time): number
+getMinute(time): number
+getSecond(time): number
+getMillisecond(time): number
+getFields(time): { hour, minute, second, millisecond }
+
+// Mutation
+with(time, { hour?, minute?, second?, millisecond? }, options?): Iso.Time
+add(time, durationLike, options?): Iso.Time
+subtract(time, durationLike, options?): Iso.Time
+
+// Comparison
+until(time, other, options?): Iso.Duration
+since(time, other, options?): Iso.Duration
+equals(time, other): boolean
+compare(one, two): number
+
+// Conversion
+toDateTime(time, date: Iso.Date): Iso.DateTime
+toZonedDateTime(time, { date, timeZone }): Iso.ZonedDateTime
+
+// Formatting
+format(time, formatString): string
+from(item, options?): Iso.Time
+chain(time): ITimeChain
+```
+
+## dateTimeFns
+
+```ts
+now(timeZone?: string): Iso.DateTime
+fromNumbers(year, month, day, hour?, minute?, second?, millisecond?): Iso.DateTime
+isValid(dateTime: unknown): dateTime is Iso.DateTime
+assertIsValid(dateTime: unknown): asserts dateTime is Iso.DateTime
+
+// Getters
+getYear(dt): number
+getMonth(dt): number
+getDay(dt): number
+getHour(dt): number
+getMinute(dt): number
+getSecond(dt): number
+getMillisecond(dt): number
+getDayOfWeek(dt): number
+getDayOfYear(dt): number
+getWeekOfYear(dt): number
+getDaysInYear(dt): number
+getDaysInMonth(dt): number
+getInLeapYear(dt): boolean
+getFields(dt): { year, month, day, hour, minute, second, millisecond }
+
+// Mutation
+with(dt, { year?, month?, day?, hour?, minute?, second?, millisecond? }, options?): Iso.DateTime
+withTime(dt, time?: Iso.Time): Iso.DateTime
+withDate(dt, date: Iso.Date): Iso.DateTime
+add(dt, durationLike, options?): Iso.DateTime
+subtract(dt, durationLike, options?): Iso.DateTime
+
+// Comparison
+until(from, until, options?): Iso.Duration
+since(dt, other, options?): Iso.Duration
+round(dt, { smallestUnit, roundingIncrement?, roundingMode? }): Iso.DateTime
+equals(dt, other): boolean
+isEqual(dt, other): boolean
+isBefore(dt, other): boolean
+isAfter(dt, other): boolean
+isEqualOrBefore(dt, other): boolean
+isEqualOrAfter(dt, other): boolean
+compare(one, two): number
+
+// Conversion
+toZonedDateTime(dt, timeZone, options?): Iso.ZonedDateTime
+toDate(dt): Iso.Date
+toTime(dt): Iso.Time
+toYearMonth(dt): Iso.YearMonth
+toMonthDay(dt): Iso.MonthDay
+
+// Formatting
+format(dt, formatString): string
+from(item, options?): Iso.DateTime
+chain(dt): IDateTimeChain
+```
+
+## instantFns
+
+```ts
+now(): Iso.Instant
+fromEpochMilliseconds(ms: number): Iso.Instant
+fromEpochSeconds(s: number): Iso.Instant
+isValid(instant: unknown): instant is Iso.Instant
+assertIsValid(instant: unknown): asserts instant is Iso.Instant
+
+// Getters
+getEpochSeconds(instant): number
+getEpochMilliseconds(instant): number
+
+// Mutation
+add(instant, durationLike): Iso.Instant
+subtract(instant, durationLike): Iso.Instant
+
+// Comparison
+until(from, until, options?): Iso.Duration
+since(to, since, options?): Iso.Duration
+round(instant, { smallestUnit?, roundingIncrement?, roundingMode? }): Iso.Instant
+equals(instant, other): boolean
+isEqual(instant, other): boolean
+isBefore(instant, other): boolean
+isAfter(instant, other): boolean
+isEqualOrBefore(instant, other): boolean
+isEqualOrAfter(instant, other): boolean
+compare(one, two): number
+
+// Conversion
+toZonedDateTime(instant, timeZone: string): Iso.ZonedDateTime
+toJsDate(instant): Date
+formatISO9075(instant): string
+
+from(item): Iso.Instant
+chain(instant): IInstantChain
+```
+
+## zonedDateTimeFns
+
+```ts
+now(timeZone?: string): Iso.ZonedDateTime
+currentTimeZone(): string
+fromEpochMilliseconds(ms: number, timeZone: string): Iso.ZonedDateTime
+isValid(zdt: unknown): zdt is Iso.ZonedDateTime
+assertIsValid(zdt: unknown): asserts zdt is Iso.ZonedDateTime
+
+// Getters
+getTimeZone(zdt): string
+getYear(zdt): number
+getMonth(zdt): number
+getDay(zdt): number
+getHour(zdt): number
+getMinute(zdt): number
+getSecond(zdt): number
+getMillisecond(zdt): number
+getEpochSeconds(zdt): number
+getEpochMilliseconds(zdt): number
+getDayOfWeek(zdt): number
+getDayOfYear(zdt): number
+getWeekOfYear(zdt): number
+getHoursInDay(zdt): number
+getDaysInMonth(zdt): number
+getDaysInYear(zdt): number
+inLeapYear(zdt): boolean
+getOffset(zdt): string
+getOffsetMilliseconds(zdt): number
+getFields(zdt): { year, month, day, hour, minute, second, millisecond, offset, timeZone }
+
+// Mutation
+with(zdt, { year?, month?, day?, hour?, minute?, second?, millisecond? }, options?): Iso.ZonedDateTime
+withDate(zdt, date: Iso.Date | DateSlots): Iso.ZonedDateTime
+withTime(zdt, time: Iso.Time | Partial<TimeSlots>): Iso.ZonedDateTime
+withTimeZone(zdt, timeZone: string): Iso.ZonedDateTime
+add(zdt, durationLike, options?): Iso.ZonedDateTime
+subtract(zdt, durationLike, options?): Iso.ZonedDateTime
+
+// Comparison
+until(zdt, other, options?): Iso.Duration
+since(zdt, other, options?): Iso.Duration
+round(zdt, { smallestUnit, roundingIncrement?, roundingMode? }): Iso.ZonedDateTime
+equals(zdt, other): boolean
+startOfDay(zdt): Iso.ZonedDateTime
+
+// Conversion
+toInstant(zdt): Iso.Instant
+toDate(zdt): Iso.Date
+toTime(zdt): Iso.Time
+toDateTime(zdt): Iso.DateTime
+toYearMonth(zdt): Iso.YearMonth
+toMonthDay(zdt): Iso.MonthDay
+
+// Formatting
+format(zdt, formatString): string
+from(item, options?): Iso.ZonedDateTime
+compare(one, two): number
+chain(zdt): IZonedDateTimeChain
+```
+
+## yearMonthFns
+
+```ts
+fromNumbers(year: number, month: number): Iso.YearMonth
+isValid(ym: unknown): ym is Iso.YearMonth
+assertIsValid(ym: unknown): asserts ym is Iso.YearMonth
+
+// Getters
+getYear(ym): number
+getMonth(ym): number
+getDaysInMonth(ym): number
+getDaysInYear(ym): number
+inLeapYear(ym): boolean
+getFields(ym): { year, month }
+
+// Mutation
+with(ym, { year?, month? }, options?): Iso.YearMonth
+add(ym, durationLike, options?): Iso.YearMonth
+subtract(ym, durationLike, options?): Iso.YearMonth
+
+// Comparison
+until(ym, other, options?): Iso.Duration
+since(ym, other, options?): Iso.Duration
+equals(ym, other): boolean
+isEqual(ym, other): boolean
+isBefore(ym, other): boolean
+isAfter(ym, other): boolean
+isEqualOrBefore(ym, other): boolean
+isEqualOrAfter(ym, other): boolean
+compare(one, two): number
+
+// Conversion
+toDate(ym, day: number): Iso.Date
+
+// Formatting
+format(ym, formatString): string
+from(item, options?): Iso.YearMonth
+chain(ym): IYearMonthChain
+```
+
+## monthDayFns
+
+```ts
+fromNumbers(month: number, day: number): Iso.MonthDay
+isValid(md: unknown): md is Iso.MonthDay
+assertIsValid(md: unknown): asserts md is Iso.MonthDay
+
+// Getters
+getDay(md): number
+getMonth(md): number
+getFields(md): { month, day }
+
+// Mutation
+with(md, { month, day }, options?): Iso.MonthDay
+
+// Comparison
+equals(md, other): boolean
+compare(one, two): number
+
+// Conversion
+toDate(md, year: number): Iso.Date
+
+// Formatting
+format(md, formatString): string
+from(item, options?): Iso.MonthDay
+chain(md): IMonthDayChain
+```
+
+## durationFns
+
+```ts
+fromNumbers(years?, months?, weeks?, days?, hours?, minutes?, seconds?, milliseconds?): Iso.Duration
+isValid(duration: unknown): duration is Iso.Duration
+assertIsValid(duration: unknown): asserts duration is Iso.Duration
+
+// Getters
+getYears(d): number
+getMonths(d): number
+getWeeks(d): number
+getDays(d): number
+getHours(d): number
+getMinutes(d): number
+getSeconds(d): number
+getMilliseconds(d): number
+getSign(d): number
+isBlank(d): boolean
+getFields(d): { years, months, weeks, days, hours, minutes, seconds, milliseconds }
+
+// Mutation
+with(d, { years?, months?, weeks?, days?, hours?, minutes?, seconds?, milliseconds? }): Iso.Duration
+negated(d): Iso.Duration
+abs(d): Iso.Duration
+add(d, other, options?): Iso.Duration
+subtract(d, other, options?): Iso.Duration
+
+// Rounding & totals
+round(d, { largestUnit?, smallestUnit?, roundingIncrement?, roundingMode?, relativeTo? }): Iso.Duration
+total(d, { unit, relativeTo? }): number
+
+// Comparison
+compare(one, two, options?): number
+
+from(item): Iso.Duration
+chain(d): IDurationChain
+```
+
+## Chaining
+
+All `*Fns` exports have a `.chain(value)` method returning a chainable wrapper. Call `.value()` to unwrap:
+
+```ts
+const result = dateFns.chain('2024-01-15')
+  .add({ months: 1 })
+  .subtract({ days: 5 })
+  .value()
+// '2024-02-10'
+```
+
+## Format Patterns
+
+Format strings use Unicode Technical Standard #35 (date-fns style):
+
+| Token | Meaning | Example |
+|-------|---------|---------|
+| `yyyy` | 4-digit year | `2024` |
+| `yy` | 2-digit year | `24` |
+| `MM` | Month (zero-padded) | `01` |
+| `M` | Month | `1` |
+| `MMM` | Month abbreviation | `Jan` |
+| `MMMM` | Month full name | `January` |
+| `dd` | Day (zero-padded) | `05` |
+| `d` | Day | `5` |
+| `iiii` | Weekday full name | `Monday` |
+| `iii` | Weekday abbreviation | `Mon` |
+| `HH` | Hour 0-23 (zero-padded) | `09` |
+| `hh` | Hour 1-12 (zero-padded) | `09` |
+| `mm` | Minute (zero-padded) | `05` |
+| `ss` | Second (zero-padded) | `03` |
+| `SSS` | Milliseconds | `123` |
+| `a` | AM/PM | `AM` |
+| `P` | Localized date | `04/29/2024` |
+| `pp` | Localized time | `12:00:00 AM` |
+| `Pp` | Localized date+time | `04/29/2024, 12:00 AM` |
+| `X`/`XX`/`XXX` | Timezone (ISO w/ Z) | `-08:00`, `Z` |
+| `x`/`xx`/`xxx` | Timezone (ISO w/o Z) | `-08:00`, `+00:00` |
+| `O`/`OOOO` | Timezone (GMT) | `GMT-8`, `GMT-08:00` |
+
+Escape literals with single quotes: `format(date, "h 'o''clock'")` => `"3 o'clock"`