feat(utils): extRegex

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

__tests__/types/index.ts

@@ -4,3 +4,4 @@
  */
 
 export type { default as RegExpArray } from './reg-exp-array'
+export type { default as Regex } from './regex'

__tests__/types/regex.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Test Type Definitions - Regex
+ * @module tests/types/Regex
+ */
+
+/**
+ * Object containing testable {@linkcode RegExp} properties.
+ */
+type Regex = Pick<
+  RegExp,
+  | 'dotAll'
+  | 'flags'
+  | 'global'
+  | 'ignoreCase'
+  | 'multiline'
+  | 'source'
+  | 'sticky'
+  | 'unicode'
+>
+
+export type { Regex as default }

src/index.ts

@@ -5,3 +5,4 @@
 
 export * from './interfaces'
 export * from './regex'
+export * from './utils'

src/utils/__tests__/ext-regex.spec-d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Type Tests - extRegex
+ * @module ext-regex/utils/tests/unit-d/extRegex
+ */
+
+import type { Options } from '#src/interfaces'
+import type testSubject from '../ext-regex'
+
+describe('unit-d:utils/extRegex', () => {
+  it('should be callable with [string, Options?]', () => {
+    // Arrange
+    type Expected = [ext: string, options?: Options | undefined]
+
+    // Expect
+    expectTypeOf<typeof testSubject>().parameters.toEqualTypeOf<Expected>()
+  })
+
+  it('should return RegExp', () => {
+    expectTypeOf<typeof testSubject>().returns.toEqualTypeOf<RegExp>()
+  })
+})

src/utils/__tests__/ext-regex.spec.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Unit Tests - extRegex
+ * @module ext-regex/utils/tests/unit/extRegex
+ */
+
+import type { Regex } from '#tests/types'
+import * as pathe from '@flex-development/pathe'
+import testSubject from '../ext-regex'
+
+describe('unit:utils/extRegex', () => {
+  it('should return regular expression matching ext', () => {
+    // Arrange
+    const cases: [...Parameters<typeof testSubject>, Regex][] = [
+      [
+        '.html',
+        undefined,
+        {
+          dotAll: false,
+          flags: '',
+          global: false,
+          ignoreCase: false,
+          multiline: false,
+          source: '\\.html(?=\\s*$)',
+          sticky: false,
+          unicode: false
+        }
+      ],
+      [
+        'html',
+        { flags: 'gi' },
+        {
+          dotAll: false,
+          flags: 'gi',
+          global: true,
+          ignoreCase: true,
+          multiline: false,
+          source: '\\.html(?=\\s*$)',
+          sticky: false,
+          unicode: false
+        }
+      ]
+    ]
+
+    // Act + Expect
+    cases.forEach(([ext, options, expected]) => {
+      const result = testSubject(ext, options)
+
+      expect(pathe.formatExt(ext)).to.match(result)
+      expect(result).to.have.property('dotAll').equal(expected.dotAll)
+      expect(result).to.have.property('flags').equal(expected.flags)
+      expect(result).to.have.property('ignoreCase').equal(expected.ignoreCase)
+      expect(result).to.have.property('multiline').equal(expected.multiline)
+      expect(result).to.have.property('source').equal(expected.source)
+      expect(result).to.have.property('sticky').equal(expected.sticky)
+      expect(result).to.have.property('unicode').equal(expected.unicode)
+    })
+  })
+})

src/utils/ext-regex.ts

@@ -0,0 +1,56 @@
+/**
+ * @file Utilities - extRegex
+ * @module ext-regex/utils/extRegex
+ */
+
+import type { Options } from '#src/interfaces'
+import * as internal from '#src/internal'
+import * as errnode from '@flex-development/errnode'
+import * as pathe from '@flex-development/pathe'
+import { isNIL, type LiteralUnion } from '@flex-development/tutils'
+
+/**
+ * Creates a regular expression matching the given file extension, `ext`.
+ *
+ * The file extension need not begin with a dot character (`'.'`).
+ *
+ * Throws `ERR_INVALID_ARG_TYPE` if the given file extension is not a string.
+ *
+ * @see {@linkcode pathe.Ext}
+ * @see {@linkcode errnode.ERR_INVALID_ARG_TYPE}
+ *
+ * @param {LiteralUnion<pathe.Ext, string>} ext - File extension to evaluate
+ * @param {Options?} [options] - Regular expression options
+ * @return {RegExp} Regular expression matching `ext`
+ * @throws {errnode.NodeError<TypeError>} If `ext` is not a string
+ */
+const extRegex = (
+  ext: LiteralUnion<pathe.Ext, string>,
+  options: Options = {}
+): RegExp => {
+  const { flags } = options
+
+  // ensure ext is a string
+  internal.validateString(ext, 'ext')
+
+  // ensure flags is a string if defined
+  !isNIL(flags) && internal.validateString(flags, 'flags')
+
+  /**
+   * Regex pattern for {@linkcode ext}.
+   *
+   * Special characters are escaped. A backslash escape (`\\`) is used whenever
+   * valid. A `\x2d` escape is used when the former would be disallowed by
+   * stricter Unicode pattern grammar.
+   *
+   * @const {string} pattern
+   */
+  const pattern: string = pathe
+    .formatExt(ext.trim())
+    .replace(/[$()*+.?[\\\]^{|}]/g, '\\$&')
+    .replace(/-/g, '\\x2d')
+
+  return new RegExp(pattern + '(?=\\s*$)', flags?.trim())
+}
+
+export default extRegex

src/utils/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Entry Point - Utilities
+ * @module ext-regex/utils
+ */
+
+export { default as extRegex } from './ext-regex'