feat: locale support for date filter, #567

Author: harttle

docs/source/filters/date.md

@@ -6,12 +6,15 @@ title: date
 Date filter is used to convert a timestamp into the specified format.
 
 * LiquidJS tries to conform to Shopify/Liquid, which uses Ruby's core [Time#strftime(string)](https://www.ruby-doc.org/core/Time.html#method-i-strftime). There're differences with [Ruby's format flags](https://ruby-doc.org/core/strftime_formatting_rdoc.html):
-  * `%Z` (since v10.11.1) works when there's a passed-in timezone name from `LiquidOption` or in-place value (see TimeZone below). If passed-in timezone is an offset number instead of string, it'll behave like `%z`. If there's none passed-in timezone, it returns [the runtime's default time zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone).
+  * `%Z` (since v10.11.1) is replaced by the passed-in timezone name from `LiquidOption` or in-place value (see TimeZone below). If passed-in timezone is an offset number instead of string, it'll behave like `%z`. If there's none passed-in timezone, it returns [the runtime's default time zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone).
   * LiquidJS provides an additional `%q` flag for date ordinals. e.g. `{{ '2023/02/02' | date: '%d%q of %b'}}` => `02nd of Feb`
 * Date literals are firstly converted to `Date` object via [new Date()][jsDate], that means literal values are considered in runtime's time zone by default.
 * The format filter argument is optional:
     * If not provided, it defaults to `%A, %B %-e, %Y at %-l:%M %P %z`.
     * The above default can be overridden by [`dateFormat`](/api/interfaces/LiquidOptions.html#dateFormat) LiquidJS option.
+* LiquidJS `date` supports locale specific weekdays and month names, which will fallback to English where `Intl` is not supported.
+    * Ordinals (`%q`) and Jekyll specific date filters are English-only.
+    * [`locale`](/api/interfaces/LiquidOptions.html#locale) can be set when creating Liquid instance. Defaults to `Intl.DateTimeFormat().resolvedOptions.locale`).
 
 ### Examples
 ```liquid

src/context/context.ts

@@ -43,7 +43,7 @@ export class Context {
     this.strictVariables = renderOptions.strictVariables ?? this.opts.strictVariables
     this.ownPropertyOnly = renderOptions.ownPropertyOnly ?? opts.ownPropertyOnly
     this.memoryLimit = memoryLimit ?? new Limiter('memory alloc', renderOptions.memoryLimit ?? opts.memoryLimit)
-    this.renderLimit = renderLimit ?? new Limiter('template render', performance.now() + (renderOptions.templateLimit ?? opts.renderLimit))
+    this.renderLimit = renderLimit ?? new Limiter('template render', performance.now() + (renderOptions.renderLimit ?? opts.renderLimit))
   }
   public getRegister (key: string) {
     return (this.registers[key] = this.registers[key] || {})

src/filters/array.ts

@@ -175,7 +175,6 @@ export function * find<T extends object> (this: FilterImpl, arr: T[], property:
     const value = yield evalToken(token, this.context.spawn(item))
     if (equals(value, expected)) return item
   }
-  return null
 }
 
 export function * find_exp<T extends object> (this: FilterImpl, arr: T[], itemName: string, exp: string): IterableIterator<unknown> {
@@ -185,7 +184,6 @@ export function * find_exp<T extends object> (this: FilterImpl, arr: T[], itemNa
     const value = yield predicate.value(this.context.spawn({ [itemName]: item }))
     if (value) return item
   }
-  return null
 }
 
 export function uniq<T> (this: FilterImpl, arr: T[]): T[] {

src/filters/date.ts

@@ -1,6 +1,6 @@
-import { toValue, stringify, isString, isNumber, TimezoneDate, LiquidDate, strftime, isNil } from '../util'
+import { toValue, stringify, isString, isNumber, LiquidDate, strftime, isNil } from '../util'
 import { FilterImpl } from '../template'
-import { LiquidOptions } from '../liquid-options'
+import { NormalizedFullOptions } from '../liquid-options'
 
 export function date (this: FilterImpl, v: string | Date, format?: string, timezoneOffset?: number | string) {
   const size = ((v as string)?.length ?? 0) + (format?.length ?? 0) + ((timezoneOffset as string)?.length ?? 0)
@@ -40,33 +40,25 @@ function stringify_date (this: FilterImpl, v: string | Date, month_type: string,
   return strftime(date, `%d ${month_type} %Y`)
 }
 
-function parseDate (v: string | Date, opts: LiquidOptions, timezoneOffset?: number | string): LiquidDate | undefined {
-  let date: LiquidDate
+function parseDate (v: string | Date, opts: NormalizedFullOptions, timezoneOffset?: number | string): LiquidDate | undefined {
+  let date: LiquidDate | undefined
+  const defaultTimezoneOffset = timezoneOffset ?? opts.timezoneOffset
+  const locale = opts.locale
   v = toValue(v)
   if (v === 'now' || v === 'today') {
-    date = new Date()
+    date = new LiquidDate(Date.now(), locale, defaultTimezoneOffset)
   } else if (isNumber(v)) {
-    date = new Date(v * 1000)
+    date = new LiquidDate(v * 1000, locale, defaultTimezoneOffset)
   } else if (isString(v)) {
     if (/^\d+$/.test(v)) {
-      date = new Date(+v * 1000)
-    } else if (opts.preserveTimezones) {
-      date = TimezoneDate.createDateFixedToTimezone(v)
+      date = new LiquidDate(+v * 1000, locale, defaultTimezoneOffset)
+    } else if (opts.preserveTimezones && timezoneOffset === undefined) {
+      date = LiquidDate.createDateFixedToTimezone(v, locale)
     } else {
-      date = new Date(v)
+      date = new LiquidDate(v, locale, defaultTimezoneOffset)
     }
   } else {
-    date = v
+    date = new LiquidDate(v, locale, defaultTimezoneOffset)
   }
-  if (!isValidDate(date)) return
-  if (timezoneOffset !== undefined) {
-    date = new TimezoneDate(date, timezoneOffset)
-  } else if (!(date instanceof TimezoneDate) && opts.timezoneOffset !== undefined) {
-    date = new TimezoneDate(date, opts.timezoneOffset)
-  }
-  return date
-}
-
-function isValidDate (date: any): date is Date {
-  return (date instanceof Date || date instanceof TimezoneDate) && !isNaN(date.getTime())
+  return date.valid() ? date : undefined
 }

src/fs/loader.ts

@@ -27,7 +27,7 @@ export class Loader {
       const rRelativePath = new RegExp(['.' + sep, '..' + sep, './', '../'].map(prefix => escapeRegex(prefix)).join('|'))
       this.shouldLoadRelative = (referencedFile: string) => rRelativePath.test(referencedFile)
     } else {
-      this.shouldLoadRelative = (referencedFile: string) => false
+      this.shouldLoadRelative = (_referencedFile: string) => false
     }
     this.contains = this.options.fs.contains || (() => true)
   }

src/fs/map-fs.spec.ts

@@ -2,25 +2,38 @@ import { MapFS } from './map-fs'
 
 describe('MapFS', () => {
   const fs = new MapFS({})
-  it('should resolve relative file paths', () => {
-    expect(fs.resolve('foo/bar', 'coo', '')).toEqual('foo/bar/coo')
+  describe('#resolve()', () => {
+    it('should resolve relative file paths', () => {
+      expect(fs.resolve('foo/bar', 'coo', '')).toEqual('foo/bar/coo')
+    })
+    it('should resolve to parent', () => {
+      expect(fs.resolve('foo/bar', '../coo', '')).toEqual('foo/coo')
+    })
+    it('should resolve to root', () => {
+      expect(fs.resolve('foo/bar', '../../coo', '')).toEqual('coo')
+    })
+    it('should resolve exceeding root', () => {
+      expect(fs.resolve('foo/bar', '../../../coo', '')).toEqual('coo')
+    })
+    it('should resolve from absolute path', () => {
+      expect(fs.resolve('/foo/bar', '../../coo', '')).toEqual('/coo')
+    })
+    it('should resolve exceeding root from absolute path', () => {
+      expect(fs.resolve('/foo/bar', '../../../coo', '')).toEqual('/coo')
+    })
+    it('should resolve from invalid path', () => {
+      expect(fs.resolve('foo//bar', '../coo', '')).toEqual('foo/coo')
+    })
+    it('should resolve current path', () => {
+      expect(fs.resolve('foo/bar', '.././coo', '')).toEqual('foo/coo')
+    })
+    it('should resolve invalid path', () => {
+      expect(fs.resolve('foo/bar', '..//coo', '')).toEqual('foo/coo')
+    })
   })
-  it('should resolve to parent', () => {
-    expect(fs.resolve('foo/bar', '../coo', '')).toEqual('foo/coo')
-  })
-  it('should resolve to root', () => {
-    expect(fs.resolve('foo/bar', '../../coo', '')).toEqual('coo')
-  })
-  it('should resolve exceeding root', () => {
-    expect(fs.resolve('foo/bar', '../../../coo', '')).toEqual('coo')
-  })
-  it('should resolve from absolute path', () => {
-    expect(fs.resolve('/foo/bar', '../../coo', '')).toEqual('/coo')
-  })
-  it('should resolve exceeding root from absolute path', () => {
-    expect(fs.resolve('/foo/bar', '../../../coo', '')).toEqual('/coo')
-  })
-  it('should resolve from invalid path', () => {
-    expect(fs.resolve('foo//bar', '../coo', '')).toEqual('foo/coo')
+  describe('#.readFileSync()', () => {
+    it('should throw if not exist', () => {
+      expect(() => fs.readFileSync('foo/bar')).toThrow('NOENT: foo/bar')
+    })
   })
 })

src/index.ts

@@ -1,7 +1,7 @@
 /* istanbul ignore file */
 export const version = '[VI]{version}[/VI]'
 export * as TypeGuards from './util/type-guards'
-export { toValue, TimezoneDate, createTrie, Trie, toPromise, toValueSync, assert, LiquidError, ParseError, RenderError, UndefinedVariableError, TokenizationError, AssertionError } from './util'
+export { toValue, createTrie, Trie, toPromise, toValueSync, assert, LiquidError, ParseError, RenderError, UndefinedVariableError, TokenizationError, AssertionError } from './util'
 export { Drop } from './drop'
 export { Emitter } from './emitters'
 export { defaultOperators, Operators, evalToken, evalQuotedToken, Expression, isFalsy, isTruthy } from './render'

src/liquid-options.ts

@@ -1,4 +1,5 @@
 import { assert, isArray, isString, isFunction } from './util'
+import { getDateTimeFormat } from './util/intl'
 import { LRU, LiquidCache } from './cache'
 import { FS, LookupType } from './fs'
 import * as fs from './fs/fs-impl'
@@ -43,6 +44,8 @@ export interface LiquidOptions {
   timezoneOffset?: number | string;
   /** Default date format to use if the date filter doesn't include a format. Defaults to `%A, %B %-e, %Y at %-l:%M %P %z`. */
   dateFormat?: string;
+  /** Default locale, will be used by date filter. Defaults to system locale. */
+  locale?: string;
   /** Strip blank characters (including ` `, `\t`, and `\r`) from the right of tags (`{% %}`) until `\n` (inclusive). Defaults to `false`. */
   trimTagRight?: boolean;
   /** Similar to `trimTagRight`, whereas the `\n` is exclusive. Defaults to `false`. See Whitespace Control for details. */
@@ -138,6 +141,7 @@ export interface NormalizedFullOptions extends NormalizedOptions {
   ownPropertyOnly: boolean;
   lenientIf: boolean;
   dateFormat: string;
+  locale: string;
   trimTagRight: boolean;
   trimTagLeft: boolean;
   trimOutputRight: boolean;
@@ -168,6 +172,7 @@ export const defaultOptions: NormalizedFullOptions = {
   dynamicPartials: true,
   jsTruthy: false,
   dateFormat: '%A, %B %-e, %Y at %-l:%M %P %z',
+  locale: '',
   trimTagRight: false,
   trimTagLeft: false,
   trimOutputRight: false,
@@ -211,9 +216,9 @@ export function normalize (options: LiquidOptions): NormalizedFullOptions {
   options.partials = normalizeDirectoryList(options.partials)
   options.layouts = normalizeDirectoryList(options.layouts)
   options.outputEscape = options.outputEscape && getOutputEscapeFunction(options.outputEscape)
-  options.parseLimit = options.parseLimit || Infinity
-  options.renderLimit = options.renderLimit || Infinity
-  options.memoryLimit = options.memoryLimit || Infinity
+  if (!options.locale) {
+    options.locale = getDateTimeFormat()?.().resolvedOptions().locale ?? 'en-US'
+  }
   if (options.templates) {
     options.fs = new MapFS(options.templates)
     options.relativeReference = true

src/parser/tokenizer.ts

@@ -143,7 +143,7 @@ export class Tokenizer {
     return new HTMLToken(this.input, begin, this.p, this.file)
   }
 
-  readTagToken (options: NormalizedFullOptions = defaultOptions): TagToken {
+  readTagToken (options: NormalizedFullOptions): TagToken {
     const { file, input } = this
     const begin = this.p
     if (this.readToDelimiter(options.tagDelimiterRight) === -1) {

src/tokens/identifier-token.ts

@@ -1,5 +1,4 @@
 import { Token } from './token'
-import { NUMBER, TYPES, SIGN } from '../util'
 import { TokenKind } from '../parser'
 
 export class IdentifierToken extends Token {
@@ -13,13 +12,4 @@ export class IdentifierToken extends Token {
     super(TokenKind.Word, input, begin, end, file)
     this.content = this.getText()
   }
-  isNumber (allowSign = false) {
-    const begin = allowSign && TYPES[this.input.charCodeAt(this.begin)] & SIGN
-      ? this.begin + 1
-      : this.begin
-    for (let i = begin; i < this.end; i++) {
-      if (!(TYPES[this.input.charCodeAt(i)] & NUMBER)) return false
-    }
-    return true
-  }
 }

src/util/error.spec.ts

@@ -0,0 +1,40 @@
+import { Template } from '../template'
+import { NumberToken } from '../tokens'
+import { LiquidErrors, LiquidError, ParseError, RenderError } from './error'
+
+describe('LiquidError', () => {
+  describe('.is()', () => {
+    it('should return true for a LiquidError instance', () => {
+      const err = new Error('intended')
+      const token = new NumberToken('3', 0, 1)
+      expect(LiquidError.is(new ParseError(err, token))).toBeTruthy()
+    })
+    it('should return false for null', () => {
+      expect(LiquidError.is(null)).toBeFalsy()
+    })
+  })
+})
+
+describe('LiquidErrors', () => {
+  describe('.is()', () => {
+    it('should return true for a LiquidErrors instance', () => {
+      const err = new Error('intended')
+      const token = new NumberToken('3', 0, 1)
+      const error = new ParseError(err, token)
+      expect(LiquidErrors.is(new LiquidErrors([error]))).toBeTruthy()
+    })
+  })
+})
+
+describe('RenderError', () => {
+  describe('.is()', () => {
+    it('should return true for a RenderError instance', () => {
+      const err = new Error('intended')
+      const tpl = {
+        token: new NumberToken('3', 0, 1),
+        render: () => ''
+      } as any as Template
+      expect(RenderError.is(new RenderError(err, tpl))).toBeTruthy()
+    })
+  })
+})

src/util/index.ts

@@ -8,5 +8,5 @@ export * from './type-guards'
 export * from './async'
 export * from './strftime'
 export * from './liquid-date'
-export * from './timezone-date'
 export * from './limiter'
+export * from './intl'

src/util/intl.ts

@@ -0,0 +1,3 @@
+export function getDateTimeFormat () {
+  return (typeof Intl !== 'undefined' ? Intl.DateTimeFormat : undefined)
+}

src/util/liquid-date.spec.ts

@@ -0,0 +1,62 @@
+import { LiquidDate } from './liquid-date'
+import { disableIntl } from '../../test/stub/no-intl'
+
+describe('LiquidDate', () => {
+  describe('timezone', () => {
+    it('should respect timezone set to 00:00', () => {
+      const date = new LiquidDate('2021-10-06T14:26:00.000+08:00', 'en-US', 0)
+      expect(date.getTimezoneOffset()).toBe(0)
+      expect(date.getHours()).toBe(6)
+      expect(date.getMinutes()).toBe(26)
+    })
+    it('should respect timezone set to -06:00', () => {
+      const date = new LiquidDate('2021-10-06T14:26:00.000+08:00', 'en-US', -360)
+      expect(date.getTimezoneOffset()).toBe(-360)
+      expect(date.getMinutes()).toBe(26)
+    })
+  })
+  it('should support Date as argument', () => {
+    const date = new LiquidDate(new Date('2021-10-06T14:26:00.000+08:00'), 'en-US', 0)
+    expect(date.getHours()).toBe(6)
+  })
+  it('should support .getMilliseconds()', () => {
+    const date = new LiquidDate('2021-10-06T14:26:00.001+00:00', 'en-US', 0)
+    expect(date.getMilliseconds()).toBe(1)
+  })
+  it('should support .getDay()', () => {
+    const date = new LiquidDate('2021-12-07T00:00:00.001+08:00', 'en-US', -480)
+    expect(date.getDay()).toBe(2)
+  })
+  it('should support .toLocaleString()', () => {
+    const date = new LiquidDate('2021-10-06T00:00:00.001+00:00', 'en-US', -480)
+    expect(date.toLocaleString('en-US')).toMatch(/8:00:00\sAM$/)
+    expect(date.toLocaleString('en-US', { timeZone: 'America/New_York' })).toMatch(/8:00:00\sPM$/)
+    expect(() => date.toLocaleString()).not.toThrow()
+  })
+  it('should support .toLocaleTimeString()', () => {
+    const date = new LiquidDate('2021-10-06T00:00:00.001+00:00', 'en-US', -480)
+    expect(date.toLocaleTimeString('en-US')).toMatch(/^8:00:00\sAM$/)
+    expect(() => date.toLocaleDateString()).not.toThrow()
+  })
+  it('should support .toLocaleDateString()', () => {
+    const date = new LiquidDate('2021-10-06T22:00:00.001+00:00', 'en-US', -480)
+    expect(date.toLocaleDateString('en-US')).toBe('10/7/2021')
+    expect(() => date.toLocaleDateString()).not.toThrow()
+  })
+  describe('compatibility', () => {
+    disableIntl()
+    it('should use English months if Intl.DateTimeFormat not supported', () => {
+      expect(new LiquidDate('2021-10-06T22:00:00.001+00:00', 'en-US', -480).getLongMonthName()).toEqual('October')
+      expect(new LiquidDate('2021-10-06T22:00:00.001+00:00', 'zh-CN', -480).getLongMonthName()).toEqual('October')
+      expect(new LiquidDate('2021-10-06T22:00:00.001+00:00', 'zh-CN', -480).getShortMonthName()).toEqual('Oct')
+    })
+    it('should use English weekdays if Intl.DateTimeFormat not supported', () => {
+      expect(new LiquidDate('2024-07-21T22:00:00.001+00:00', 'en-US', 0).getLongWeekdayName()).toEqual('Sunday')
+      expect(new LiquidDate('2024-07-21T22:00:00.001+00:00', 'zh-CN', -480).getLongWeekdayName()).toEqual('Monday')
+      expect(new LiquidDate('2024-07-21T22:00:00.001+00:00', 'zh-CN', -480).getShortWeekdayName()).toEqual('Mon')
+    })
+    it('should return none for timezone if Intl.DateTimeFormat not supported', () => {
+      expect(new LiquidDate('2024-07-21T22:00:00.001', 'en-US').getTimeZoneName()).toEqual(undefined)
+    })
+  })
+})