Support literal square brackets in format strings

Allow escaping square brackets with backslashes to output them literally in formatted dates and parse them from input strings.

Author: knowledgecode

src/compile.ts

@@ -2,12 +2,24 @@
 
 export type CompiledObject = string[];
 
+// Escape sequences for literal brackets
+const LBRACKET = /\\\[/g;
+const RBRACKET = /\\\]/g;
+
+// Private Use Area characters to temporarily replace literal brackets
+const PUA_LBRACKET = /\uE000/g;
+const PUA_RBRACKET = /\uE001/g;
+
+// Regular expression to match format tokens, literal text, and escaped characters
+const REGEXP = /\[(?:[^[\]]|\[[^[\]]*])*]|([A-Za-z])\1*|\.{3}|./g;
+
 /**
  * Compiles a format string into a tokenized array for efficient parsing and formatting.
  * @param formatString - The format string to compile
  * @returns A compiled array where the first element is the original format string,
  *          followed by tokenized format components
  */
 export const compile = (formatString: string): CompiledObject => {
-  return [formatString, ...formatString.match(/\[(?:[^[\]]|\[[^[\]]*])*]|([A-Za-z])\1*|\.{3}|./g) || []];
+  const array = formatString.replace(LBRACKET, '\uE000').replace(RBRACKET, '\uE001').match(REGEXP) || [];
+  return [formatString, ...array.map(token => token.replace(PUA_LBRACKET, '[').replace(PUA_RBRACKET, ']'))];
 };

tests/compile.spec.ts

@@ -170,3 +170,8 @@ test('[empty]', () => {
   const obj = [''] as string[];
   expect(compile('')).toEqual(obj);
 });
+
+test('\\[YYYY-MM-DD\\]', () => {
+  const obj = ['\\[YYYY-MM-DD\\]', '[', 'YYYY', '-', 'MM', '-', 'DD', ']'];
+  expect(compile('\\[YYYY-MM-DD\\]')).toEqual(obj);
+});

tests/parse.spec.ts

@@ -489,6 +489,11 @@ test('                 ', () => {
   expect(Number.isNaN(parse('20151231235959900', '                 ').getTime())).toBe(true);
 });
 
+test('\\[YYYY-MM-DD HH:mm:ss\\]', () => {
+  const now = new Date(2025, 7, 23, 14, 30, 45);
+  expect(parse('[2025-08-23 14:30:45]', '\\[YYYY-MM-DD HH:mm:ss\\]')).toEqual(now);
+});
+
 describe('options', () => {
   test('hour12: h11', () => {
     expect(parse('2000-01-01 00:00 AM', 'YYYY-MM-DD hh:mm A', { hour12: 'h11' })).toEqual(new Date(2000, 0, 1, 0, 0));