cron-explain-ja/dist/index.d.cts

cron式と日本語を相互変換するライブラリ / CLI

//#region src/types.d.ts
/**
 * cron 式のフィールド識別子。
 */
type CronField = "second" | "minute" | "hour" | "dayOfMonth" | "month" | "dayOfWeek";
/**
 * 標準 cron を超える拡張構文。
 * - `L`: 月末 / 最終曜日
 * - `#`: 第 N 曜日
 * - `W`: 直近の平日
 * - `?`: 指定なし
 */
type CronExtension = "L" | "#" | "W" | "?";
/**
 * 1 フィールドの構文木。
 *
 * `nth.nth` は 1-5 が第 N 曜日、`-1` が最終曜日（`5L`）を表す。
 */
type FieldAST = {
  kind: "any";
} | {
  kind: "value";
  value: number;
} | {
  kind: "range";
  from: number;
  to: number;
} | {
  kind: "step";
  base: FieldAST;
  step: number;
} | {
  kind: "list";
  items: FieldAST[];
} | {
  kind: "last";
  offset?: number;
} | {
  kind: "nth";
  weekday: number;
  nth: number;
} | {
  kind: "nearestWeekday";
  day: number;
} | {
  kind: "noSpecific";
};
type FieldKind = FieldAST["kind"];
/**
 * cron 式全体の構文木。
 */
interface CronAST {
  seconds?: FieldAST;
  minute: FieldAST;
  hour: FieldAST;
  dayOfMonth: FieldAST;
  month: FieldAST;
  dayOfWeek: FieldAST;
}
interface ParserOptions {
  /** 6 フィールド（秒付き）として解釈する */
  seconds?: boolean;
}
interface ExplainOptions extends ParserOptions {
  /** 'casual': 「毎日午前9時」 / 'formal': 「毎日午前9時00分」 */
  style?: "casual" | "formal";
  /** '12h': 「午後3時」 / '24h': 「15時」 */
  hour?: "12h" | "24h";
  /**
   * cron 式（UTC）を読み替えるタイムゾーン。IANA のゾーン名か `'local'`。既定は 'Asia/Tokyo'
   *
   * `'UTC'` を渡すと書き換えずにそのまま説明する。
   */
  tz?: string;
  /** 文末に「（Asia/Tokyo）」とタイムゾーン名を併記する */
  showTimeZone?: boolean;
  /** 曜日を「平日」「週末」に畳むか */
  collapseWeekdays?: boolean;
}
interface FieldExplanation {
  /** 入力そのまま（正規化前） */
  raw: string;
  kind: "any" | "value" | "list" | "range" | "step" | "extension";
  /** 展開後の値。拡張構文では空配列 */
  values: number[];
  text: string;
}
interface Explanation {
  text: string;
  /** 入力（UTC）を正規化した cron 式 */
  expression: string;
  /** `tz` の壁時計に書き換えた cron 式。`fields` と `text` はこちらを説明している */
  localExpression: string;
  /** 説明に使ったタイムゾーン（IANA の正規名） */
  tz: string;
  fields: {
    second?: FieldExplanation;
    minute: FieldExplanation;
    hour: FieldExplanation;
    dayOfMonth: FieldExplanation;
    month: FieldExplanation;
    dayOfWeek: FieldExplanation;
  };
  extensions: CronExtension[];
  notes: string[];
  /** 次回 3 回。拡張構文を含む式では空配列 */
  next: Date[];
}
type TimeOfDayWord = "早朝" | "朝" | "午前" | "昼" | "正午" | "午後" | "夕方" | "夜" | "晩" | "深夜" | "夜中";
type TokenType = "FREQ" | "DOW" | "DOW_SET" | "DOM" | "DOM_SPECIAL" | "MONTH" | "TIME" | "MINUTE" | "TIME_OF_DAY" | "AMPM" | "HOUR_SPAN" | "INTERVAL" | "RANGE_FROM" | "RANGE_TO" | "NTH" | "SEP" | "AND" | "UNKNOWN";
interface Token {
  type: TokenType;
  raw: string;
  value?: unknown;
  position: number;
}
interface Ambiguity {
  field: CronField;
  question: string;
  candidates: Array<{
    value: number | string;
    label: string;
  }>;
}
interface ParseResult {
  /** UTC のサーバー向けの cron 式 */
  expression: string | null;
  /** `tz` の壁時計のままの cron 式。日本語が字面どおり指した時刻 */
  localExpression: string | null;
  /** 解釈に使ったタイムゾーン（IANA の正規名） */
  tz: string;
  /** 0.0 - 1.0 */
  confidence: number;
  ambiguities: Ambiguity[];
  notes: string[];
  /**
   * トークナイズの結果。**デバッグ用で semver の対象外**。
   *
   * 種別の追加・改名はパーサの改良に伴って起きるので、`Token` / `TokenType` の中身は
   * minor でも変わりうる。動作を分岐させる用途には使わないこと。
   */
  tokens: Token[];
}
interface ParseOptions {
  /** 曖昧な場合に ParseAmbiguityError を投げる */
  strict?: boolean;
  /** 時刻が読み取れなかったときの既定の時 */
  defaultHour?: number;
  /** 「朝」などの曖昧語に対する時の上書き */
  timeOfDay?: Partial<Record<TimeOfDayWord, number>>;
  /** L / # / W の使用を許可する（false でも生成はするが note を付ける） */
  allowExtensions?: boolean;
  /**
   * 日本語をどのタイムゾーンの壁時計として読むか。IANA のゾーン名か `'local'`。
   * 既定は 'Asia/Tokyo'。出力の cron 式は常に UTC
   */
  tz?: string;
}
interface ValidationError {
  field: CronField | "expression";
  message: string;
  position?: number;
}
interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: string[];
}
interface NextOptions extends ParserOptions {
  /** 起点。既定は現在時刻 */
  from?: Date;
  /** 取得件数。既定は 3 */
  count?: number;
}
//#endregion
//#region src/cron/next.d.ts
/**
 * cron 式の次回実行日時を求める。
 *
 * cron 式は UTC のサーバーで動くものとして解釈する。返るのは絶対時刻なので、
 * どのタイムゾーンで表示するかは呼び出し側の裁量。
 *
 * `L` / `#` / `W` を含む式は v1 では計算対象外で、空配列を返す。
 */
export declare function next(expression: string, options?: NextOptions): Date[];
//#endregion
//#region src/cron/validate.d.ts
/**
 * cron 式を検証する。構文エラーは throw せず {@link ValidationResult} として返す。
 */
export declare function validate(expression: string, options?: ParserOptions): ValidationResult;
//#endregion
//#region src/errors.d.ts
/**
 * cron 式の構文エラー。
 */
export declare class CronSyntaxError extends Error {
  readonly field?: CronField;
  readonly position?: number;
  constructor(message: string, options?: {
    field?: CronField;
    position?: number;
  });
}
/**
 * `parse({ strict: true })` で解釈が曖昧だったときに投げられる。
 */
export declare class ParseAmbiguityError extends Error {
  readonly result: ParseResult;
  constructor(message: string, result: ParseResult);
}
/**
 * タイムゾーン名を解釈できなかったときに投げられる。
 */
export declare class CronTimeZoneError extends Error {
  /** 与えられたゾーン名 */
  readonly timeZone: string;
  constructor(message: string, timeZone: string);
}
//#endregion
//#region src/explain/index.d.ts
/**
 * cron 式を 1 文の日本語に変換する。
 *
 * 式は UTC のサーバーで動くものとして読み、`options.tz`（既定 `'Asia/Tokyo'`）の
 * 壁時計に直してから日本語にする。
 *
 * ```ts
 * explain('0 4 * * 1-5'); // '平日の午後1時'（UTC 04:00 = JST 13:00）
 * explain('0 9 * * 1-5', { tz: 'UTC' }); // '平日の午前9時'（変換しない）
 * ```
 *
 * @throws {CronSyntaxError} 式が不正な場合
 * @throws {CronTimeZoneError} `tz` を解釈できない、または cron 式に書き換えられない場合
 */
export declare function explain(expression: string, options?: ExplainOptions): string;
/**
 * cron 式をフィールド別の内訳・注意書き・次回実行日時つきで説明する。
 *
 * `fields` は `options.tz` の壁時計に直したあとの値を説明する（`localExpression` と対応）。
 * `expression` は入力（UTC）を正規化したもの、`next` は UTC として解釈した絶対時刻。
 *
 * @throws {CronSyntaxError} 式が不正な場合
 * @throws {CronTimeZoneError} `tz` を解釈できない、または cron 式に書き換えられない場合
 */
export declare function explainDetailed(expression: string, options?: ExplainOptions): Explanation;
//#endregion
//#region src/parse/index.d.ts
/**
 * 日本語の予定表現を cron 式に変換する。
 *
 * 日本語は `options.tz`（既定 `'Asia/Tokyo'`）の壁時計として読み、UTC のサーバーで
 * 動かすための cron 式を返す。
 *
 * ```ts
 * parse('毎日午後1時').expression; // '0 4 * * *'（JST 13:00 = UTC 04:00）
 * parse('平日の朝9時', { tz: 'UTC' }).expression; // '0 9 * * 1-5'（変換しない）
 * ```
 *
 * @throws {ParseAmbiguityError} `strict: true` かつ解釈が曖昧な場合
 * @throws {CronTimeZoneError} `tz` を解釈できない、または UTC の cron 式に書き換えられない場合
 */
export declare function parse(text: string, options?: ParseOptions): ParseResult;
//#endregion
export type { Ambiguity, CronAST, CronExtension, CronField, ExplainOptions, Explanation, FieldAST, FieldExplanation, FieldKind, NextOptions, ParseOptions, ParseResult, ParserOptions, TimeOfDayWord, Token, TokenType, ValidationError, ValidationResult };
//# sourceMappingURL=index.d.cts.map