### TomlDate Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Documentation for the TomlDate class, including constructor, instance methods, static methods, and usage examples. ```APIDOC ## TomlDate ### Description Represents a TOML date/time value, extending the native JavaScript `Date` object with additional methods to distinguish between different types of time components (offset date-time, local date-time, local date, local time). It preserves the offset, unlike the native `Date` object which normalizes to UTC. ### Constructor `new TomlDate(value: string | Date)` ### Methods - **isDateTime()** - Returns `true` if the value is a date-time (offset or local). - **isDate()** - Returns `true` if the value is a date (local date). - **isTime()** - Returns `true` if the value is a time (local time). - **isLocal()** - Returns `true` if the value is local (no offset). - **toISOString()** - Returns the date/time in ISO 8601 format, preserving the offset. ### Static Methods - **TomlDate.wrapAsOffsetDateTime(date: Date)** - Wraps a native `Date` object as an offset date-time. - **TomlDate.wrapAsLocalDateTime(date: Date)** - Wraps a native `Date` object as a local date-time. - **TomlDate.wrapAsLocalDate(date: Date)** - Wraps a native `Date` object as a local date. - **TomlDate.wrapAsLocalTime(date: Date)** - Wraps a native `Date` object as a local time. ### Example ```js import { TomlDate } from 'smol-toml' // Offset Date Time const date = new TomlDate('1979-05-27T07:32:00.000-08:00') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, false console.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000-08:00 // Local Date Time const date = new TomlDate('1979-05-27T07:32:00.000') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, true console.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000 // Local Date const date = new TomlDate('1979-05-27') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, true, false, true console.log(date.toISOString()) // ~> 1979-05-27 // Local Time const date = new TomlDate('07:32:00') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, false, true, true console.log(date.toISOString()) // ~> 07:32:00.000 ``` ### Wrapping Example ```js import { TomlDate } from 'smol-toml' const jsDate = new Date() const offsetDateTime = TomlDate.wrapAsOffsetDateTime(jsDate) const localDateTime = TomlDate.wrapAsLocalDateTime(jsDate) const localDate = TomlDate.wrapAsLocalDate(jsDate) const localTime = TomlDate.wrapAsLocalTime(jsDate) ``` ``` -------------------------------- ### Prototype pollution example with parse Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Demonstrates the prototype pollution caveat when using the parsed object. The example shows that `parse` itself is safe, but careless use of the returned object (e.g., with `Object.assign`) can lead to prototype pollution. The library offers `keep`, `drop`, and `throw` modes to handle unsafe keys. ```javascript import { parse } from 'smol-toml' const a = parse('__proto__.b = 5') console.log(a.b) // ~> undefined const b = Object.assign({}, a) console.log(b.b) // ~> 5 ``` -------------------------------- ### Temporal output and key safety with parse() Source: https://github.com/squirrelchat/smol-toml Demonstrates the `useLegacyDate: false` option to get Temporal API output (requires a runtime with `globalThis.Temporal`), and the `unsafeKeyBehaviour` option to either throw on `__proto__`/`constructor` keys or drop them silently. ```javascript import { parse } from 'smol-toml' // Temporal API output (requires a runtime with globalThis.Temporal) const date = parse('when = 1979-05-27T07:32:00Z', { useLegacyDate: false }).when console.log(date.toString()) // '1979-05-27T07:32:00Z' // Reject documents that contain `__proto__` or `constructor` keys try { parse('__proto__.polluted = 1', { unsafeKeyBehaviour: 'throw' }) } catch (err) { console.log(err instanceof TomlError) // true } // Drop them silently const safe = parse('constructor.a = 1', { unsafeKeyBehaviour: 'drop' }) console.log(safe.constructor) // undefined ``` -------------------------------- ### Basic usage of stringify Source: https://github.com/squirrelchat/smol-toml Serializes a JavaScript object into TOML format. The example shows nested objects, arrays, and array of tables. The output is printed to the console. ```javascript import { stringify } from 'smol-toml' const toml = stringify({ title: 'TOML Example', owner: { name: 'Tom Preston-Werner', active: true, }, ports: [8001, 8001, 8002], servers: [ { name: 'alpha', ip: '10.0.0.1' }, { name: 'beta', ip: '10.0.0.2' }, ], }) console.log(toml) // title = "TOML Example" // ports = [ 8001, 8001, 8002 ] // // [owner] // name = "Tom Preston-Werner" // active = true // // [[servers]] // name = "alpha" // ip = "10.0.0.1" // // [[servers]] // name = "beta" // ip = "10.0.0.2" ``` -------------------------------- ### Catching parse errors and inspecting position data Source: https://github.com/squirrelchat/smol-toml Example of catching a TomlError from parse() and logging its message, line, column, and codeblock. The codeblock shows the offending line with a caret. ```js import { parse, TomlError } from 'smol-toml' const doc = 'a = [1, 2, ?]' try { parse(doc) } catch (err) { if (err instanceof TomlError) { console.log(err.message) console.log(err.line) // 1 console.log(err.column) // 11 console.log(err.codeblock) // 1: a = [1, 2, ?] // ^ } } ``` -------------------------------- ### Distinguishing TomlError from other failures Source: https://github.com/squirrelchat/smol-toml Example of catching a TomlError and handling other errors separately. The parse call uses a 53-bit overflow integer to trigger a TomlError when BigInt is disabled. ```js import { parse, TomlError } from 'smol-toml' try { parse('x = 9223372036854775807') // 53-bit overflow, BigInt disabled } catch (err) { if (err instanceof TomlError) { console.error(`parse failed at line ${err.line}, column ${err.column}`) } else { // e.g. a TypeError thrown before parsing began (non-string input, ...) throw err } } ``` -------------------------------- ### parse function implementation with defaults Source: https://github.com/squirrelchat/smol-toml Shows how the parse function applies option defaults. The context object uses maxDepth ?? 1000, integersAsBigInt ?? false, useLegacyDate ?? true, and maps unsafeKeyBehaviour to internal codes. ```TypeScript export function parse(toml: string, options: ParseOptions = {}): TomlTable { let ctx: ParseContext = { s: toml, p: 0, d: options.maxDepth ?? 1000, bi: options.integersAsBigInt ?? false, ld: options.useLegacyDate ?? true, uk: options.unsafeKeyBehaviour === 'throw' ? 2 : options.unsafeKeyBehaviour === 'drop' ? 1 : 0, } // ... } ``` -------------------------------- ### Basic parse and stringify usage Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Shows the basic usage of the `parse` and `stringify` functions from the `smol-toml` library. The `parse` function converts a TOML string into a JavaScript object, and `stringify` converts an object back into a TOML string. ```javascript import { parse, stringify } from 'smol-toml' const doc = '...' const parsed = parse(doc) console.log(parsed) const toml = stringify(parsed) console.log(toml) ``` -------------------------------- ### Namespace import for smol-toml Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Alternative import style that mimics the JSON global, allowing access to functions like `stringify` through a namespace object. ```javascript import * as TOML from 'smol-toml' TOML.stringify({ ... }) ``` -------------------------------- ### Create TomlDate from TOML strings and check date/time types Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Creates TomlDate instances from TOML date/time strings and demonstrates the isDateTime(), isDate(), isTime(), and isLocal() type-checking methods along with toISOString() output. Note that TomlDate preserves the offset, unlike native Date which normalizes to UTC, and is limited to millisecond precision. ```javascript import { TomlDate } from 'smol-toml' // Offset Date Time const date = new TomlDate('1979-05-27T07:32:00.000-08:00') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, false console.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000-08:00 // Local Date Time const date = new TomlDate('1979-05-27T07:32:00.000') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, true console.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000 // Local Date const date = new TomlDate('1979-05-27') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, true, false, true console.log(date.toISOString()) // ~> 1979-05-27 // Local Time const date = new TomlDate('07:32:00') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, false, true, true console.log(date.toISOString()) // ~> 07:32:00.000 ``` -------------------------------- ### Wrap native Date with TomlDate.wrapAs* methods Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Wraps a native JavaScript Date object into TomlDate instances using the wrapAsOffsetDateTime, wrapAsLocalDateTime, wrapAsLocalDate, and wrapAsLocalTime methods to represent different TOML date/time types. ```javascript import { TomlDate } from 'smol-toml' const jsDate = new Date() const offsetDateTime = TomlDate.wrapAsOffsetDateTime(jsDate) const localDateTime = TomlDate.wrapAsLocalDateTime(jsDate) const localDate = TomlDate.wrapAsLocalDate(jsDate) const localTime = TomlDate.wrapAsLocalTime(jsDate) ``` -------------------------------- ### parse options Source: https://github.com/squirrelchat/smol-toml Configuration options for the parse function, passed as the second argument. These options control integer parsing, date handling, unsafe key behavior, and maximum nesting depth. ```APIDOC ## ParseOptions ### Description Options object passed as the second argument to the `parse` function to configure parsing behavior. ### Parameters #### Options - **integersAsBigInt** (`IntegersAsBigInt` — `undefined | boolean | 'asNeeded'`) - Optional - Default: `false` - Parse integers as `BigInt`. `true` converts every integer to `bigint` (approx. 5% parse slowdown); `'asNeeded'` converts only integers exceeding the safe `number` range. `false`/`undefined` keeps `number`, and out-of-range integers throw `TomlError` (`'integer value cannot be represented losslessly'`). - **useLegacyDate** (`boolean`) - Optional - Default: `true` - `true` parses date/time literals into `TomlDate` (a `Date` subclass, millisecond precision, gracefully accepts e.g. 2020-02-30). `false` parses into Temporal objects (`Temporal.ZonedDateTime` / `PlainDateTime` / `PlainDate` / `PlainTime`), which are stricter and require a runtime with `globalThis.Temporal`. - **unsafeKeyBehaviour** (`UnsafeKeyBehaviour` — `'keep' | 'drop' | 'throw'`) - Optional - Default: `'keep'` - Handling of `__proto__` / `constructor` keys: `'keep'` stores them as own enumerable properties (pollution-safe); `'drop'` omits them from the result; `'throw'` rejects the whole document with `TomlError` (`'document contains an unsafe property'`). - **maxDepth** (`number`) - Optional - Default: `1000` - Maximum recursion budget for nested arrays/inline tables. Exceeding it aborts parsing with `TomlError` (`'document contains excessively nested structures. aborting.'`). ### Behavioral effect on the return type - `integersAsBigInt: true | 'asNeeded'` selects the first `parse` overload and the result type is `TomlTable` (may contain `bigint`). - Otherwise the result type is `TomlTableWithoutBigInt`. ``` -------------------------------- ### Wrapping native Date objects and checking validity with TomlDate Source: https://github.com/squirrelchat/smol-toml Demonstrates wrapping a native Date into TOML date-time types using wrapAsOffsetDateTime, wrapAsLocalDateTime, wrapAsLocalDate, and wrapAsLocalTime. Also shows that string input can produce an invalid TomlDate, which isValid() detects, and that TomlDate round-trips through stringify. ```javascript import { TomlDate } from 'smol-toml' import { stringify } from 'smol-toml' const jsDate = new Date() const offsetDateTime = TomlDate.wrapAsOffsetDateTime(jsDate) const localDateTime = TomlDate.wrapAsLocalDateTime(jsDate) const localDate = TomlDate.wrapAsLocalDate(jsDate) const localTime = TomlDate.wrapAsLocalTime(jsDate) // Values created with wrapAs* are always valid; string input can fail: const invalid = new TomlDate('not a date') if (!invalid.isValid()) { console.log('unparseable input -> Invalid Date') } // TomlDate round-trips through stringify/parse const toml = stringify({ when: localDate }) // when = 2024-05-27 ``` -------------------------------- ### stringify Source: https://github.com/squirrelchat/smol-toml Serializes a JavaScript object into a TOML string. Accepts optional configuration options to control maximum nesting depth, number formatting, and temporal value handling. ```APIDOC ## stringify ### Description Serializes a JavaScript object into a TOML string. Accepts optional configuration options to control maximum nesting depth, number formatting, and temporal value handling. ### Signature ```ts export function stringify ( obj: any, { maxDepth = 1000, numbersAsFloat = false, strictTemporal = false }: { maxDepth?: number, numbersAsFloat?: boolean, strictTemporal?: boolean } = {}, ) { // ... } ``` ### Parameters #### obj - **obj** (any) - Required - The object to serialize. #### Options - **maxDepth** (number) - Optional - Default: `1000` - Maximum nesting depth for tables, arrays of tables, and inline structures. Exceeding it throws `Error` (`'Could not stringify the object: maximum object depth exceeded'`). - **numbersAsFloat** (boolean) - Optional - Default: `false` - `false`: numbers without a decimal part serialize as integers (e.g. `1`); `true`: such numbers serialize as floats (`1.0`), so only `bigint` values produce integer literals — end-to-end type preservation with `parse(..., { integersAsBigInt: true })`. - **strictTemporal** (boolean) - Optional - Default: `false` - `false`: `ZonedDateTime` values are downgraded to their UTC offset (IANA timezone and calendar information silently lost); `true`: throws `TypeError` for ZonedDateTimes with a non-offset timezone (see the accepted-offset list in [errors.md](errors.md)) and for any date/time value with a `calendarId` other than `'iso8601'`. ### Accepted timezone forms under `strictTemporal: true` From the source check (`src/stringify.ts:98–107`), a `ZonedDateTime.timeZoneId` is **accepted** when it is: - a plain offset starting with `+` or `-` (e.g. `+02:00`), or - one of the UTC aliases `UTC`, `UCT`, `Universal`, `Zulu`, or - prefixed with `GMT` (including `GMT` itself) or `Greenwich`, or - prefixed with `Etc/` (e.g. `Etc/UTC`). Anything else (e.g. `Europe/Paris`) throws in strict mode. ``` -------------------------------- ### Serialize TOML with numbers as floats Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Serialize numbers as floating point values by passing `numbersAsFloat: true` to the `stringify` function. This ensures that only BigInts are serialized as integers, preserving type information end-to-end. ```js import { stringify } from 'smol-toml' const obj = { ... } const toml = stringify(obj, { numbersAsFloat: true }) ``` -------------------------------- ### Parse TOML with BigInt integers Source: https://github.com/squirrelchat/smol-toml/blob/mistress/README.md Enable BigInt parsing for all integers by passing `integersAsBigInt: true` to the `parse` function. This preserves type information for integers beyond 53 bits at a cost of approximately 5% slowdown. Use `"asNeeded"` to only use BigInt for numbers that cannot be safely represented as plain JavaScript numbers. ```js import { parse } from 'smol-toml' const doc = '...' const parsed = parse(doc, { integersAsBigInt: true }) ``` -------------------------------- ### ParseOptions interface definition Source: https://github.com/squirrelchat/smol-toml Defines the options object accepted by the parse function. All options are optional with defaults: integersAsBigInt (false), useLegacyDate (true), unsafeKeyBehaviour ('keep'), maxDepth (1000). ```TypeScript export interface ParseOptions { /** * Whether to parse integers as {@link BigInt} or not. * * Use the special value `"asNeeded"` to only use {@link BigInt} for * integers that cannot be safely represented as JavaScript numbers. * * @defaultValue `false` * @since 1.4.0 */ integersAsBigInt?: IntegersAsBigInt /** * Whether to use the legacy {@link TomlDate}, instead of the new * {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal | Temporal API}. * * @defaultValue `true` * @since 1.9.0 */ useLegacyDate?: boolean /** * Behaviour of the library when encountering a potentially unsafe property (`__proto__`, `constructor`). * * @defaultValue `'keep'` * @since 1.9.0 */ unsafeKeyBehaviour?: UnsafeKeyBehaviour /** * Maximum permitted inline object/array depth. * * @defaultValue `1000` * @since 1.9.0 */ maxDepth?: number } ``` -------------------------------- ### Type preservation, round-trip, and error handling Source: https://github.com/squirrelchat/smol-toml Demonstrates how stringify handles different types, including numbersAsFloat option, null/undefined values, and error cases. Shows that null/undefined object values are ignored, but rejected inside arrays. Also shows legacy TomlDate serialization. ```javascript import { parse, stringify, TomlDate } from 'smol-toml' // numbersAsFloat preserves the integer/float distinction; only bigint // serializes as an integer literal afterwards const out = stringify({ km: 1, ratio: 1.5, big: 9223372036854775807n }, { numbersAsFloat: true }) // km = 1.0 // ratio = 1.5 // big = 9223372036854775807 // null / undefined object values are ignored... console.log(stringify({ a: 1, b: null, c: undefined })) // 'a = 1\n' // ...but are rejected inside arrays try { stringify({ arr: [1, null] }) } catch (err) { console.log(err.message) // 'arrays cannot contain null or undefined values' } // Legacy TomlDate objects serialize as Offset Date-Time in UTC console.log(stringify({ when: new TomlDate('1979-05-27T07:32:00-08:00') })) // when = 1979-05-27T15:32:00.000Z ``` -------------------------------- ### constructor(date: string | Date) Source: https://github.com/squirrelchat/smol-toml Creates a new TomlDate instance from a string or Date object. The string can be a TOML date/time literal or any value accepted by the native Date constructor. ```APIDOC ## Constructor ### Description Creates a new TomlDate instance. When given a string, it classifies the value using the DATE_TIME_RE regex; values that don't match produce an invalid TomlDate (isValid() returns false). ### Parameters - **date** (string | Date) - Required - Any value accepted by the native Date constructor, or a TOML date/time literal string. ### Example ```ts const date = new TomlDate('1979-05-27T07:32:00Z'); ``` ``` -------------------------------- ### new TomlDate(value) Source: https://github.com/squirrelchat/smol-toml Creates a TomlDate instance from a TOML date/time string or a native Date object. Provides methods to distinguish between date-time, date, time, and local types, and to check validity. ```APIDOC ## Constructor: new TomlDate(value) ### Description Creates a TomlDate instance from a TOML date/time string or a native Date object. Provides methods to distinguish between date-time, date, time, and local types, and to check validity. ### Parameters - **value** (string | Date) - Required - A TOML date/time string or a native Date object. ### Methods - **isDateTime()** (boolean) - Returns true if the value represents a date-time (with offset or local). - **isDate()** (boolean) - Returns true if the value represents a date only. - **isTime()** (boolean) - Returns true if the value represents a time only. - **isLocal()** (boolean) - Returns true if the value is local (no offset). - **toISOString()** (string) - Returns the ISO 8601 representation of the value. - **isValid()** (boolean) - Returns true if the value is a valid date/time. ### Example ```js import { TomlDate } from 'smol-toml' const date = new TomlDate('1979-05-27T07:32:00.000-08:00') console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // true, false, false, false console.log(date.toISOString()) // '1979-05-27T07:32:00.000-08:00' const time = new TomlDate('07:32:00') console.log(time.isDateTime(), time.isDate(), time.isTime(), time.isLocal()) // false, false, true, true console.log(time.toISOString()) // '07:32:00.000' ``` ``` -------------------------------- ### parse(toml, options?) Source: https://github.com/squirrelchat/smol-toml Parses a TOML document string into a JavaScript object. This is the main entry point for the smol-toml library and is synchronous and spec-compliant with TOML v1.1.0. ```APIDOC ## parse(toml, options?) ### Description Parses a TOML document string into a JavaScript object. This is the main entry point for the smol-toml library and is synchronous and spec-compliant with TOML v1.1.0. ### Signature ```ts export function parse(toml: string, options?: ParseOptions & { integersAsBigInt: Exclude }): TomlTable export function parse(toml: string, options?: ParseOptions): TomlTableWithoutBigInt export function parse(toml: string, options: ParseOptions = {}): TomlTable ``` ### Parameters - `toml` (string) - Required - The TOML document to parse. A leading UTF-16 BOM (`\uFEFF`) is skipped. Empty documents parse to an empty table. - `options` (ParseOptions) - Optional - Parse options; see table below. ### ParseOptions - `integersAsBigInt` (IntegersAsBigInt) - Default: `false` - Parse integers as `BigInt`. `'asNeeded'` uses `BigInt` only for integers that cannot be represented losslessly as a JavaScript `number`. - `useLegacyDate` (boolean) - Default: `true` - Use the legacy `TomlDate` (a `Date` subclass) instead of the Temporal API for date/time values. - `unsafeKeyBehaviour` (UnsafeKeyBehaviour) - Default: `'keep'` - How to deal with keys named `__proto__` or `constructor`. - `maxDepth` (number) - Default: `1000` - Maximum permitted inline object/array nesting depth. ### Return Value - `TomlTable` or `TomlTableWithoutBigInt` - The parsed TOML document as a JavaScript object. The return type depends on the `integersAsBigInt` option. ``` -------------------------------- ### ParseOptions interface definition Source: https://github.com/squirrelchat/smol-toml Configuration options for parsing TOML. See configuration.md and parse API reference. ```ts export interface ParseOptions { integersAsBigInt?: IntegersAsBigInt useLegacyDate?: boolean unsafeKeyBehaviour?: UnsafeKeyBehaviour maxDepth?: number } ``` -------------------------------- ### Big integers and error handling with parse() Source: https://github.com/squirrelchat/smol-toml Shows how to parse large integers losslessly using the `integersAsBigInt: 'asNeeded'` option, and how to catch `TomlError` when a number exceeds 53 bits and BigInt is disabled. The error object provides `message`, `line`, `column`, and `codeblock` properties. ```javascript import { parse, TomlError } from 'smol-toml' // `asNeeded` keeps plain numbers small, and uses BigInt only where a // lossless `number` representation is impossible const parsed = parse('huge = 9223372036854775807', { integersAsBigInt: 'asNeeded' }) console.log(parsed.huge) // 9223372036854775807n try { parse('a = 9223372036854775807') // exceeds 53 bits, BigInt disabled } catch (err) { if (err instanceof TomlError) { console.log(err.message) // 'Invalid TOML document: integer value cannot be represented losslessly\n\n...' console.log(err.line) // 1 console.log(err.column) // 5 console.log(err.codeblock) // annotated source snippet } } ``` -------------------------------- ### toISOString() override Source: https://github.com/squirrelchat/smol-toml Returns string — restores the 'as authored' representation. Output varies by kind: Local Date (YYYY-MM-DD), Local Time (HH:MM:SS.mmm), Local DateTime (full ISO without trailing Z), Offset DateTime with Z/z (unchanged), Offset DateTime with other offset (re-anchored to authored offset). Source: src/date.ts:135. ```TypeScript override toISOString() { // ... } ``` -------------------------------- ### wrapAsLocalDateTime (static) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as a Local Date-Time (offset reset to null). ```APIDOC ## wrapAsLocalDateTime (static) ### Description Wraps a native Date into a TomlDate marked as a Local Date-Time (offset reset to null). ### Method wrapAsLocalDateTime(jsDate: Date) ### Parameters - **jsDate** (Date) - Required - The native Date to wrap. ### Returns - **TomlDate** - The wrapped TomlDate. ### Source `src/date.ts:170` ``` -------------------------------- ### wrapAsOffsetDateTime (static) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as an Offset Date-Time. The offset parameter is used verbatim by toISOString() without validation. ```APIDOC ## wrapAsOffsetDateTime (static) ### Description Wraps a native Date into a TomlDate marked as an Offset Date-Time. The offset parameter is used verbatim by toISOString() without validation. ### Method wrapAsOffsetDateTime(jsDate: Date, offset = 'Z') ### Parameters - **jsDate** (Date) - Required - The native Date to wrap. - **offset** (string) - Optional - Offset string such as `'Z'` or `'-08:00'` (default `'Z'`). ### Returns - **TomlDate** - The wrapped TomlDate. ### Source `src/date.ts:164` ``` -------------------------------- ### wrapAsLocalDate (static) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as a Local Date (time component dropped). ```APIDOC ## wrapAsLocalDate (static) ### Description Wraps a native Date into a TomlDate marked as a Local Date (time component dropped). ### Method wrapAsLocalDate(jsDate: Date) ### Parameters - **jsDate** (Date) - Required - The native Date to wrap. ### Returns - **TomlDate** - The wrapped TomlDate. ### Source `src/date.ts:176` ``` -------------------------------- ### wrapAsLocalTime (static) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as a Local Time (date component dropped). ```APIDOC ## wrapAsLocalTime (static) ### Description Wraps a native Date into a TomlDate marked as a Local Time (date component dropped). ### Method wrapAsLocalTime(jsDate: Date) ### Parameters - **jsDate** (Date) - Required - The native Date to wrap. ### Returns - **TomlDate** - The wrapped TomlDate. ### Source `src/date.ts:183` ``` -------------------------------- ### toISOString() (override) Source: https://github.com/squirrelchat/smol-toml Returns the 'as authored' representation of the TomlDate value. The output format depends on the type of date/time value. ```APIDOC ## toISOString() (override) ### Description Returns the 'as authored' representation of the TomlDate value. The output format depends on the type of date/time value. ### Method toISOString() ### Returns - **string** - The 'as authored' representation: - Local Date: `YYYY-MM-DD` (`iso.slice(0, 10)`) - Local Time: `HH:MM:SS.mmm` (`iso.slice(11, 23)`) - Local DateTime: Full ISO string without trailing `Z` - Offset DateTime (`Z`/`z`): Full ISO string, unchanged - Offset DateTime (other offset): ISO string re-anchored to the authored offset (e.g. `1979-05-27T07:32:00.000-08:00`) ### Source `src/date.ts:135` ``` -------------------------------- ### TomlDate constructor overload 2 — public Source: https://github.com/squirrelchat/smol-toml Public constructor accepting any value valid for the native Date constructor or a TOML date/time literal string. Invalid strings produce an invalid TomlDate where isValid() returns false. ```ts constructor(date: string | Date) ``` -------------------------------- ### wrapAsOffsetDateTime static method Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as an Offset Date-Time. offset is a string such as 'Z' or '-08:00' (default 'Z'); used verbatim by toISOString() without validation. Returns TomlDate. Source: src/date.ts:164. ```TypeScript static wrapAsOffsetDateTime(jsDate: Date, offset = 'Z') { ``` -------------------------------- ### TomlDate constructor overload 1 — internal fast path Source: https://github.com/squirrelchat/smol-toml Internal constructor overload used by the parser (src/extract.ts). Skips regex validation for a fast position-based parse. The unsafeDelim flag normalizes space separators to 'T'. ```ts constructor(date: string, fasttype: TomlDateFastTypeId, unsafeDelim: boolean | undefined) ``` -------------------------------- ### wrapAsLocalDateTime static method Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as a Local Date-Time (offset reset to null). Returns TomlDate. Source: src/date.ts:170. ```TypeScript static wrapAsLocalDateTime(jsDate: Date) { ``` -------------------------------- ### TomlError constructor signature Source: https://github.com/squirrelchat/smol-toml The constructor takes a message and options. The message is prefixed with 'Invalid TOML document: ' and the options include the full TOML document and a pointer offset. ```ts constructor(message: string, options: TomlErrorOptions) ``` -------------------------------- ### TomlError constructor Source: https://github.com/squirrelchat/smol-toml Creates a new TomlError instance with a message and options containing the TOML document and pointer position. The error message is formatted with line/column information and an annotated code block. ```APIDOC ## TomlError constructor ### Description Creates a new TomlError instance with a message and options containing the TOML document and pointer position. The error message is formatted with line/column information and an annotated code block. ### Method constructor ### Signature ```ts constructor(message: string, options: TomlErrorOptions) ``` ### Parameters - `message` (string) - Required - Short description of the error, e.g. `'invalid value'`. It is prefixed with `Invalid TOML document: ` by the constructor. - `options` (TomlErrorOptions) - Required - See below. #### TomlErrorOptions ```ts export type TomlErrorOptions = ErrorOptions & { toml: string ptr: number } ``` - `toml` (string) - Required - The full TOML document, used to compute `line`/`column`/`codeblock`. - `ptr` (number) - Required - Absolute character offset into `toml` at which the error occurred. - `cause?` (ErrorOptions) - Optional - Standard `Error` option, forwarded to the `Error` constructor. ### Properties - `message` (string) - Formatted as `Invalid TOML document: \n\n` by the constructor. - `line` (number) - 1-based line number of the error position. - `column` (number) - 1-based column (character offset on the line) of the error position. - `codeblock` (string) - The up-to-three source lines surrounding the error (previous, offending, next), each prefixed with right-aligned line numbers, with a `^` caret underlining the offending column. ### Example ```js import { parse, TomlError } from 'smol-toml' const doc = 'a = [1, 2, ?]' try { parse(doc) } catch (err) { if (err instanceof TomlError) { console.log(err.message) console.log(err.line) // 1 console.log(err.column) // 11 console.log(err.codeblock) // 1: a = [1, 2, ?] // ^ } } ``` ``` -------------------------------- ### stringify Source: https://github.com/squirrelchat/smol-toml Converts a JavaScript object graph into a TOML document string. The output always ends with a trailing newline. ```APIDOC ## stringify ### Description Converts a JavaScript object graph into a TOML document string. The output always ends with a trailing newline. ### Signature ```ts export function stringify ( obj: any, { maxDepth = 1000, numbersAsFloat = false, strictTemporal = false }: { maxDepth?: number, numbersAsFloat?: boolean, strictTemporal?: boolean } = {}, ) { // implementation } ``` ### Parameters - **obj** (any) - Required - The object to serialize. Must be a plain object (`extendedTypeOf(obj) === 'object'`); arrays, primitives, etc. are rejected with a `TypeError`. - **options.maxDepth** (number) - Optional - Default: `1000` - Maximum permitted nesting depth for tables/arrays/tables-array. Exceeding it throws `Error`. - **options.numbersAsFloat** (boolean) - Optional - Default: `false` - When `false` (default), numbers without a decimal part are serialized as integers; with `true`, they are rendered as floats (e.g. `1` becomes `1.0`) so that only `bigint` values serialize as integers. - **options.strictTemporal** (boolean) - Optional - Default: `false` - When `true`, `Temporal.ZonedDateTime` values carrying an IANA timezone (anything other than a plain offset, `UTC` and its aliases, `GMT*`, `Etc/*`) or a non-`iso8601` calendar are rejected with a `TypeError`. ### Returns A TOML document string. The output always ends with a trailing newline. ``` -------------------------------- ### parse() Source: https://github.com/squirrelchat/smol-toml Parses a TOML document string and returns a JavaScript object. The return value type depends on the `options.integersAsBigInt` flag, and date/time values are either `TomlDate` instances or Temporal objects depending on `useLegacyDate`. ```APIDOC ## parse() ### Description Parses a TOML document string and returns a JavaScript object. The return value type depends on the `options.integersAsBigInt` flag, and date/time values are either `TomlDate` instances or Temporal objects depending on `useLegacyDate`. ### Return Value - With `options.integersAsBigInt` truthy: `TomlTable` — a nested object whose integer values may be `bigint`. - Otherwise: `TomlTableWithoutBigInt` — the same structure without `bigint` values. - Date/time values are `TomlDate` instances (with `useLegacyDate: true`, the default) or Temporal objects (`Temporal.ZonedDateTime`, `Temporal.PlainDateTime`, `Temporal.PlainDate`, `Temporal.PlainTime`) with `useLegacyDate: false`. - The root object (and every nested table) is created via `Object.create(null)`, so it has a **null prototype** (`src/parse.ts:211`). The returned object has no inherited properties, but a plain `'__proto__'` key is stored as an own enumerable property (inheritance-safe, see Key safety in the README). ### Behavior Notes - Booleans, strings (basic, literal, multiline, and literal-multiline), integers (decimal, hex `0x`, octal `0o`, binary `0b`), floats, `inf`/`nan`, arrays, inline tables, standard tables, dotted keys, and table arrays are supported. - Integers larger than 53 bits throw `TomlError` (`'integer value cannot be represented losslessly'`) unless `integersAsBigInt` is used — see [errors.md](../errors.md). - With `unsafeKeyBehaviour: 'keep'` (default), `__proto__` keys are stored via `Object.defineProperty` and never trigger prototype pollution. - Comments and whitespace are skipped; control characters inside comments or strings are rejected. ### Throws | Error | Condition | |-------|-----------| | `TomlError` | Any syntactically invalid or semantically conflicting TOML document, including unsafe keys when `unsafeKeyBehaviour: 'throw'`. Exact conditions are catalogued in [errors.md](../errors.md). | ``` -------------------------------- ### stringify error handling Source: https://github.com/squirrelchat/smol-toml The stringify function raises standard JavaScript errors for specific serialization conditions. Catch RangeError for bad surrogates in keys, TypeError for value-type problems, and Error for depth exceeded. ```APIDOC ## stringify error handling ### Description The stringify function raises standard JavaScript errors for specific serialization conditions. Catch RangeError for bad surrogates in keys, TypeError for value-type problems, and Error for depth exceeded. ### Example ```js import { stringify } from 'smol-toml' try { stringify(obj) } catch (err) { if (err instanceof RangeError) { // bad surrogate in a key } else if (err instanceof TypeError) { // value-type problems } else if (err instanceof Error) { // depth exceeded } } ``` ``` -------------------------------- ### wrapAsLocalDate static method Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as a Local Date (time component dropped). Returns TomlDate. Source: src/date.ts:176. ```TypeScript static wrapAsLocalDate(jsDate: Date) { ``` -------------------------------- ### TomlDate.wrapAsOffsetDateTime(date) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date object as an offset date-time TomlDate. The resulting value is always valid. ```APIDOC ## Static Method: TomlDate.wrapAsOffsetDateTime(date) ### Description Wraps a native Date object as an offset date-time TomlDate. The resulting value is always valid. ### Parameters - **date** (Date) - Required - A native JavaScript Date object. ### Returns - **TomlDate** - A TomlDate instance representing an offset date-time. ### Example ```js import { TomlDate } from 'smol-toml' const jsDate = new Date() const offsetDateTime = TomlDate.wrapAsOffsetDateTime(jsDate) ``` ``` -------------------------------- ### wrapAsLocalTime static method Source: https://github.com/squirrelchat/smol-toml Wraps a native Date into a TomlDate marked as a Local Time (date component dropped). Returns TomlDate. Source: src/date.ts:183. ```TypeScript static wrapAsLocalTime(jsDate: Date) { ``` -------------------------------- ### Basic usage of parse() Source: https://github.com/squirrelchat/smol-toml Parses a TOML document string into a JavaScript object. Dates become Date objects by default, arrays become arrays, and booleans become booleans. ```javascript import { parse } from 'smol-toml' const doc = ` title = "TOML Example" [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00 [database] ports = [ 8001, 8001, 8002 ] enabled = true ` const obj = parse(doc) console.log(obj.title) // 'TOML Example' console.log(obj.owner.name) // 'Tom Preston-Werner' console.log(obj.owner.dob.toISOString()) // '1979-05-27T07:32:00.000-08:00' console.log(obj.database.ports) // [ 8001, 8001, 8002 ] ``` -------------------------------- ### TomlDate.wrapAsLocalDate(date) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date object as a local date TomlDate. The resulting value is always valid. ```APIDOC ## Static Method: TomlDate.wrapAsLocalDate(date) ### Description Wraps a native Date object as a local date TomlDate. The resulting value is always valid. ### Parameters - **date** (Date) - Required - A native JavaScript Date object. ### Returns - **TomlDate** - A TomlDate instance representing a local date. ### Example ```js import { TomlDate } from 'smol-toml' const jsDate = new Date() const localDate = TomlDate.wrapAsLocalDate(jsDate) ``` ``` -------------------------------- ### TomlDate.wrapAsLocalDateTime(date) Source: https://github.com/squirrelchat/smol-toml Wraps a native Date object as a local date-time TomlDate. The resulting value is always valid. ```APIDOC ## Static Method: TomlDate.wrapAsLocalDateTime(date) ### Description Wraps a native Date object as a local date-time TomlDate. The resulting value is always valid. ### Parameters - **date** (Date) - Required - A native JavaScript Date object. ### Returns - **TomlDate** - A TomlDate instance representing a local date-time. ### Example ```js import { TomlDate } from 'smol-toml' const jsDate = new Date() const localDateTime = TomlDate.wrapAsLocalDateTime(jsDate) ``` ``` -------------------------------- ### TomlErrorOptions type definition Source: https://github.com/squirrelchat/smol-toml Options for the TomlError constructor. See tomlerror.md API reference. ```ts export type TomlErrorOptions = ErrorOptions & { toml: string ptr: number } ``` -------------------------------- ### isTime() method Source: https://github.com/squirrelchat/smol-toml Returns true when the value is a Local Time only (HH:MM:SS(.fff)). Source: src/date.ts:127. ```TypeScript isTime() { return this.#hasTime && !this.#hasDate } ```