amazon-ion/ion-js v3.0.0

on GitHub

This release includes many changes to the ion-js API. The following identifies API changes since 3.0.0-beta.3. Additional information can be found in the API documentation. Anything not present in the API documentation is internal and subject to change in the future.

The following are known limitations:

• int values are restricted to 32 bits: [-2147483648, 2147483647]
• character escape sequences are not fully supported in strings, symbols, and clobs
• no support for:
  • ints denoted in binary
  • underscore characters in ints, decimals, or floats
  • shared symbol tables
  • symboltokens
  • SID0 ($0)

Note: this release targets Node environments only and has not been verified to work in any browsers.

Associated milestone: Release V3.0

Full list of changes: v3.0.0-beta.3..v3.0.0

API Changes

General

• The API has been narrowed to the following modules:
  • Ion
  • Decimal
  • Reader
  • Timestamp
  • Type
  • Types
  • Writer
• Callers using IonEventStream to transfer the contents of a reader to a writer should use the new Writer.writeValue() or Writer.writeValues() methods instead

Ion

• removed:
  • asSpan()
  • get_buf_type()
  • isSourceType()
  • makeBinaryReader(): use makeReader() instead
  • makeTextReader(): use makeReader() instead

Decimal

• added:
  • ONE
  • compareTo()
  • intValue()
  • numberValue()
• modified:
  • constructor now expects a coefficient and exponent, both numbers
  • toString() now returns a string using scientific notation if an exponent is needed
• removed:
  • NULL
  • getDigits()
  • getExponent()
  • getNumber(): use numberValue() instead
  • isNegativeZero()
  • isNull()
  • isZero()
  • isZeroZero()
  • stringValue()

IonType

• renamed:
  • bid to binaryTypeId
  • container to isContainer
  • lob to isLob
  • num to isNumeric
  • scalar to isScalar

IonTypes

• removed: BOC, DATAGRAM

Reader

• *Value() methods now return null instead of undefined.
• added:
  • type()
• modified:
  • next() returns null when not positioned on a value
  • value() now throws for container types
  • booleanValue() throws if the reader is not pointed at a BOOLEAN value
  • byteValue() throws if the reader is not pointed at a CLOB or BLOB value
  • decimalValue() throws if the reader is not pointed at a DECIMAL value
  • numberValue() throws if the reader is not pointed at a INT or FLOAT value
  • stringValue() throws if the reader is not pointed at a STRING and SYMBOL value
  • timestampValue() throws if the reader is not pointed at a TIMESTAMP value

Timestamp

• added:
  • compareTo()
  • getDate()
  • getSecondsDecimal()
  • getSecondsInt()
• renamed:
  • getOffset() to getLocalOffset()
• modified:
  • constructor signature has changed (removed precision; offset and year are now required; other parameters are optional; and seconds, if specified, must be a number or Decimal)
• removed:
  • checkValid()
  • dataModelEquals(): use compareTo() instead
  • getEpochMilliseconds(): use getDate().getTime() instead
  • getZuluDay(): use getDate().getUTCDate() instead
  • getZuluHour(): use getDate().getUTCHours() instead
  • getZuluMinute(): use getDate().getUTCMinutes() instead
  • getZuluMonth(): use getDate().getUTCMonth() instead
  • getZuluSeconds(): use getDate().getUTCSeconds() instead
  • getZuluYear(): use getDate().getUTCFullYear() instead
  • isNull()
  • numberValue(): use getDate().getTime() instead
  • stringValue(): use toString() instead

TimestampPrecision (was Precision)

• removed: EMPTY, NULL

Writer

• containers must now be explicitly closed (auto-close has been removed to avoid masking programming errors)
• annotations is no longer a parameter of individual write*() methods; instead, call addAnnotation() or setAnnotations() prior to one of the write*() methods
• null container values (null.list, null.sexp, null.struct) are no longer written by writeList([], true), writeSexp([], true), or writeStruct([], true); these values are now written via writeNull(IonTypes.LIST), writeNull(IonTypes.SEXP), and writeNull(IonTypes.STRUCT)
• TypeCodes has been removed in favor of IonType/IonTypes
• added:
  • writeValue()
  • writeValues()
• modified:
  • writeNull(TypeCode) is now writeNull(IonType)
• renamed:
  • endContainer() to stepOut()
  • writeList() to stepIn(IonTypes.LIST)
  • writeSexp() to stepIn(IonTypes.SEXP)
  • writeStruct() to stepIn(IonTypes.STRUCT)