Add constants (minTime, maxTime) (date-fns#1076) (closes date-fns#609)

* Add constants: `minTime`, `maxTime`. * Integrate constants into build system & docs.
elmomalmo · Jul 12, 2019 · d48eeaf · d48eeaf
1 parent c93cf26
commit d48eeaf
Show file tree

Hide file tree

Showing 27 changed files with 289 additions and 55 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -713,6 +713,12 @@ for the list of changes made since `v2.0.0-alpha.1`.
 
 - `parseISO` function that parses ISO 8601 strings. See [#1023](https://github.com/date-fns/date-fns/pull/1023).
 
+- Add constants:
+
+  - `maxTime`
+
+  - `minTime`
+
 - New locales:
 
   - [Norwegian Nynorsk locale (nn)](https://github.com/date-fns/date-fns/pull/1172)

diff --git a/docs/constants.md b/docs/constants.md
@@ -0,0 +1,47 @@
+# Constants
+
+date-fns provides with a number of useful constants.
+
+## Usage
+
+The constants could be imported from `date-fns/constants` or directly
+from `date-fns`:
+
+```js
+import { maxTime } from 'date-fns/constants'
+import { minTime } from 'date-fns'
+
+function isAllowedTime(time) {
+  return time <= maxTime && time >= minTime
+}
+```
+
+## Constants
+
+### `maxTime`
+
+Maximum allowed time:
+
+```js
+import { maxTime } from 'date-fns'
+
+const isValid = 8640000000000001 <= maxTime
+//=> false
+
+new Date(8640000000000001)
+//=> Invalid Date
+```
+
+### `minTime`
+
+Minimum allowed time:
+
+```js
+import { minTime } from 'date-fns'
+
+const isValid = -8640000000000001 >= minTime
+//=> false
+
+new Date(-8640000000000001)
+//=> Invalid Date
+```
diff --git a/docs/index.js b/docs/index.js
@@ -47,6 +47,14 @@ module.exports = {
       description: 'Contribution manual',
       path: path.join(__dirname, '..', 'CONTRIBUTING.md')
     },
+    {
+      type: 'markdown',
+      urlId: 'Constants',
+      category: 'General',
+      title: 'Constants',
+      description: 'Useful constants',
+      path: path.join(__dirname, 'constants.md')
+    },
     {
       type: 'markdown',
       urlId: 'I18n',

diff --git a/examples/flow/constants.js.flow b/examples/flow/constants.js.flow
@@ -0,0 +1,11 @@
+// @flow
+
+const dateFns = require('date-fns')
+const constants = require('date-fns/constants')
+const { minTime: fpMinTime } = require('date-fns/fp')
+
+console.log(
+  dateFns.maxTime === 8640000000000000 &&
+    dateFns.minTime === constants.minTime &&
+    constants.minTime === fpMinTime
+)
diff --git a/examples/flow/package.json b/examples/flow/package.json
@@ -14,13 +14,15 @@
     "build": "yarn run build-date-fns && yarn run flow-check && yarn run build-babel",
     "flow-check": "flow check",
     "build-date-fns": "env PACKAGE_OUTPUT_PATH=\"$(pwd)/node_modules/date-fns\" ../../scripts/build/package.sh",
-    "build-babel": "yarn run build-babel-example && yarn run build-babel-fp && yarn run build-babel-misc",
+    "build-babel": "yarn run build-babel-example && yarn run build-babel-fp && yarn run build-babel-misc && yarn build-babel-constants",
     "build-babel-example": "mkdir -p dist && babel example.js.flow --out-file dist/example.js",
     "build-babel-fp": "mkdir -p dist && babel fp.js.flow --out-file dist/fp.js",
     "build-babel-misc": "mkdir -p dist && babel misc.js.flow --out-file dist/misc.js",
-    "test": "yarn run test-example && yarn run test-fp && yarn run test-misc",
+    "build-babel-constants": "mkdir -p dist && babel constants.js.flow --out-file dist/constants.js",
+    "test": "yarn run test-example && yarn run test-fp && yarn run test-misc && yarn run test-constants",
     "test-example": "test $(env TZ=UTC node ./dist/example.js) = true",
     "test-fp": "test $(env TZ=UTC node ./dist/fp.js) = true",
-    "test-misc": "test $(env TZ=UTC node ./dist/misc.js) = true"
+    "test-misc": "test $(env TZ=UTC node ./dist/misc.js) = true",
+    "test-constants": "test $(node ./dist/constants.js) = true"
   }
 }
diff --git a/examples/typescript/constants.ts b/examples/typescript/constants.ts
@@ -0,0 +1,9 @@
+import { maxTime as rootMaxTime, minTime as rootMinTime } from 'date-fns'
+import { minTime } from 'date-fns/constants'
+import { minTime as fpMinTime } from 'date-fns/fp'
+
+console.log(
+  rootMaxTime === 8640000000000000 &&
+    rootMinTime === minTime &&
+    minTime === fpMinTime
+)
diff --git a/examples/typescript/package.json b/examples/typescript/package.json
@@ -12,11 +12,12 @@
   "scripts": {
     "build": "yarn run build-date-fns && yarn run build-typescript && yarn run build-webpack",
     "build-date-fns": "env PACKAGE_OUTPUT_PATH=\"$(pwd)/node_modules/date-fns\" ../../scripts/build/package.sh",
-    "build-typescript": "tsc --outDir dist example.ts fp.ts misc.ts",
-    "build-webpack": "webpack example=./dist/example.js fp=./dist/fp misc=./dist/misc.js --output-path dist --output-filename [name].bundle.js",
-    "test": "yarn run test-example && yarn run test-fp && yarn run test-misc",
+    "build-typescript": "tsc --outDir dist example.ts fp.ts misc.ts constants.ts",
+    "build-webpack": "webpack example=./dist/example.js fp=./dist/fp misc=./dist/misc.js constants=./dist/constants.js --output-path dist --output-filename [name].bundle.js",
+    "test": "yarn run test-example && yarn run test-fp && yarn run test-misc && yarn run test-constants",
     "test-example": "test $(env TZ=UTC node ./dist/example.bundle.js) = true",
     "test-fp": "test $(env TZ=UTC node ./dist/fp.bundle.js) = true",
-    "test-misc": "test $(env TZ=UTC node ./dist/misc.bundle.js) = true"
+    "test-misc": "test $(env TZ=UTC node ./dist/misc.bundle.js) = true",
+    "test-constants": "test $(node ./dist/constants.bundle.js) = true"
   }
 }
diff --git a/examples/webpack-1.x/constants.js b/examples/webpack-1.x/constants.js
@@ -0,0 +1,9 @@
+const dateFns = require('date-fns')
+const constants = require('date-fns/constants')
+const { minTime: fpMinTime } = require('date-fns/fp')
+
+console.log(
+  dateFns.maxTime === 8640000000000000 &&
+    dateFns.minTime === constants.minTime &&
+    constants.minTime === fpMinTime
+)
diff --git a/examples/webpack-1.x/package.json b/examples/webpack-1.x/package.json
@@ -14,15 +14,17 @@
   "scripts": {
     "build": "yarn run build-date-fns && yarn run build-webpack && yarn run build-babili",
     "build-date-fns": "env PACKAGE_OUTPUT_PATH=\"$(pwd)/node_modules/date-fns\" ../../scripts/build/package.sh",
-    "build-webpack": "webpack example=./example.js fp=./fp.js misc=./misc.js --output-path dist --output-file [name].js",
-    "build-babili": "yarn run build-babili-example && yarn run build-babili-fp && yarn run build-babili-misc && yarn run stats-size",
+    "build-webpack": "webpack example=./example.js fp=./fp.js misc=./misc.js constants=./constants.js --output-path dist --output-file [name].js",
+    "build-babili": "yarn run build-babili-example && yarn run build-babili-fp && yarn run build-babili-misc && yarn build-babili-constants && yarn run stats-size",
     "build-babili-example": "babili dist/example.js --out-file dist/example.min.js --minified --no-comments",
     "build-babili-fp": "babili dist/fp.js --out-file dist/fp.min.js --minified --no-comments",
     "build-babili-misc": "babili dist/misc.js --out-file dist/misc.min.js --minified --no-comments",
+    "build-babili-constants": "babili dist/constants.js --out-file dist/constants.min.js --minified --no-comments",
     "stats-size": "gzip-size dist/example.min.js | pretty-bytes",
-    "test": "yarn run test-example && yarn run test-fp && yarn run test-misc",
+    "test": "yarn test-example && yarn test-fp && yarn test-misc && yarn test-constants",
     "test-example": "test $(env TZ=UTC node ./dist/example.min.js) = true",
     "test-fp": "test $(env TZ=UTC node ./dist/fp.min.js) = true",
-    "test-misc": "test $(env TZ=UTC node ./dist/misc.min.js) = true"
+    "test-misc": "test $(env TZ=UTC node ./dist/misc.min.js) = true",
+    "test-constants": "test $(node ./dist/constants.min.js) = true"
   }
 }
diff --git a/examples/webpack-4.x/constants.js b/examples/webpack-4.x/constants.js
@@ -0,0 +1,9 @@
+import { maxTime as rootMaxTime, minTime as rootMinTime } from 'date-fns'
+import { minTime } from 'date-fns/constants'
+import { minTime as fpMinTime } from 'date-fns/fp'
+
+console.log(
+  rootMaxTime === 8640000000000000 &&
+    rootMinTime === minTime &&
+    minTime === fpMinTime
+)
diff --git a/examples/webpack-4.x/package.json b/examples/webpack-4.x/package.json
@@ -14,16 +14,18 @@
   "scripts": {
     "build": "yarn build-date-fns && yarn build-webpack && yarn build-uglify",
     "build-date-fns": "env PACKAGE_OUTPUT_PATH=\"$(pwd)/node_modules/date-fns\" ../../scripts/build/package.sh",
-    "build-webpack": "webpack example=./example.js fp=./fp.js misc=./misc.js minimal=./minimal.js --output-path dist --output-filename [name].js",
-    "build-uglify": "yarn build-uglify-example && yarn build-uglify-fp && yarn build-uglify-misc && yarn build-uglify-minimal && yarn stats-size",
+    "build-webpack": "webpack example=./example.js fp=./fp.js misc=./misc.js minimal=./minimal.js constants=./constants.js --output-path dist --output-filename [name].js",
+    "build-uglify": "yarn build-uglify-example && yarn build-uglify-fp && yarn build-uglify-misc && yarn build-uglify-minimal && yarn build-uglify-constants && yarn stats-size",
     "build-uglify-example": "node_modules/uglify-es/bin/uglifyjs --compress --mangle --output dist/example.min.js dist/example.js",
     "build-uglify-fp": "node_modules/uglify-es/bin/uglifyjs --compress --mangle --output dist/fp.min.js dist/fp.js",
     "build-uglify-misc": "node_modules/uglify-es/bin/uglifyjs --compress --mangle --output dist/misc.min.js dist/misc.js",
     "build-uglify-minimal": "node_modules/uglify-es/bin/uglifyjs --compress --mangle --output dist/minimal.min.js dist/minimal.js",
+    "build-uglify-constants": "node_modules/uglify-es/bin/uglifyjs --compress --mangle --output dist/constants.min.js dist/constants.js",
     "stats-size": "echo \"Minimal size: $(gzip-size dist/minimal.min.js)\nFormat size: $(gzip-size dist/example.min.js)\nFP size: $(gzip-size dist/fp.min.js)\nMisc size: $(gzip-size dist/misc.min.js)\"",
-    "test": "yarn test-example && yarn test-fp && yarn test-misc",
+    "test": "yarn test-example && yarn test-fp && yarn test-misc && yarn test-constants",
     "test-example": "test $(env TZ=UTC node ./dist/example.min.js) = true",
     "test-fp": "test $(env TZ=UTC node ./dist/fp.min.js) = true",
-    "test-misc": "test $(env TZ=UTC node ./dist/misc.min.js) = true"
+    "test-misc": "test $(env TZ=UTC node ./dist/misc.min.js) = true",
+    "test-constants": "test $(env TZ=UTC node ./dist/constants.min.js) = true"
   }
 }
diff --git a/scripts/_lib/getConstants.js b/scripts/_lib/getConstants.js
@@ -0,0 +1,13 @@
+const path = require('path')
+const jsDocParser = require('jsdoc-to-markdown')
+
+module.exports = getConstants
+
+function getConstants() {
+  return jsDocParser
+    .getJsdocDataSync({
+      files: path.resolve(process.cwd(), 'src/constants/index.js'),
+      'no-cache': true
+    })
+    .filter(c => c.kind === 'constant' && !c.undocumented)
+}
diff --git a/scripts/_lib/listFns.js b/scripts/_lib/listFns.js
@@ -7,6 +7,7 @@ const ignoredFiles = [
   'locale',
   'esm',
   'fp',
+  'constants',
   'index.js',
   'test.js',
   'index.js.flow',

diff --git a/scripts/build/_lib/typings/flow.js b/scripts/build/_lib/typings/flow.js
@@ -55,7 +55,7 @@ function generateFlowFnTyping(fn, aliasDeclarations) {
   writeFile(`src/${title}/index.js.flow`, typingFile)
 }
 
-function generateFlowFnIndexTyping(fns, aliasDeclarations) {
+function generateFlowFnIndexTyping(fns, aliasDeclarations, constants) {
   const fnsDeclarations = fns.map(({ title, args, content }) => {
     const params = getParams(args, { leftBorder: '(', rightBorder: ')' })
     const returns = getType(content.returns[0].type.names)
@@ -66,7 +66,10 @@ function generateFlowFnIndexTyping(fns, aliasDeclarations) {
     ${addSeparator(aliasDeclarations, '\n')}
 
     declare module.exports: {
-      ${addSeparator(fnsDeclarations, ',\n')}
+      ${addSeparator(
+        fnsDeclarations.concat(generateConstantsDeclarations(constants)),
+        ',\n'
+      )}
     }
   `
 
@@ -89,7 +92,7 @@ function generateFlowFPFnTyping(fn, aliasDeclarations) {
   writeFile(`src/fp/${title}/index.js.flow`, typingFile)
 }
 
-function generateFlowFPFnIndexTyping(fns, aliasDeclarations) {
+function generateFlowFPFnIndexTyping(fns, aliasDeclarations, constants) {
   const fnsDeclarations = fns.map(
     ({ title, args, content }) =>
       `${title}: ${getFPFnType(args, content.returns[0].type.names)}`
@@ -101,7 +104,10 @@ function generateFlowFPFnIndexTyping(fns, aliasDeclarations) {
     ${addSeparator(getFlowFPTypeAliases(), '\n')}
 
     declare module.exports: {
-      ${addSeparator(fnsDeclarations, ',')}
+      ${addSeparator(
+        fnsDeclarations.concat(generateConstantsDeclarations(constants)),
+        ','
+      )}
     }
   `
 
@@ -132,7 +138,7 @@ function generateFlowLocaleIndexTyping(locales, localeAliasDeclaration) {
   writeFile('src/locale/index.js.flow', typingFile)
 }
 
-function generateFlowTypings(fns, aliases, locales) {
+function generateFlowTypings(fns, aliases, locales, constants) {
   const aliasDeclarations = aliases.map(getFlowTypeAlias)
   const localeAliasDeclaration = getFlowTypeAlias(
     aliases.find(alias => alias.title === 'Locale')
@@ -152,15 +158,21 @@ function generateFlowTypings(fns, aliases, locales) {
 
   generateFlowFnIndexTyping(
     fns.filter(({ isFPFn }) => !isFPFn),
-    aliasDeclarations
+    aliasDeclarations,
+    constants
   )
   generateFlowFPFnIndexTyping(
     fns.filter(({ isFPFn }) => isFPFn),
-    aliasDeclarations
+    aliasDeclarations,
+    constants
   )
   generateFlowLocaleIndexTyping(locales, localeAliasDeclaration)
 }
 
+function generateConstantsDeclarations(constants) {
+  return constants.map(c => `${c.name}: ${c.type.names.join(' | ')}`)
+}
+
 function writeFile(relativePath, content) {
   return fs.writeFileSync(
     path.resolve(process.cwd(), relativePath),

diff --git a/scripts/build/_lib/typings/typeScript.js b/scripts/build/_lib/typings/typeScript.js
@@ -73,12 +73,19 @@ function getExportedTypeScriptTypeAliases(aliases) {
   `
 }
 
-function getTypeScriptDateFnsModuleDefinition(submodule, fns) {
+function getTypeScriptDateFnsModuleDefinition(
+  submodule,
+  fns,
+  constantsDefinitions
+) {
   const moduleName = `date-fns${submodule}`
 
   const definition = formatBlock`
     declare module '${moduleName}' {
-      ${addSeparator(fns.map(getTypeScriptFnDefinition), '\n')}
+      ${addSeparator(
+        fns.map(getTypeScriptFnDefinition).concat(constantsDefinitions),
+        '\n'
+      )}
     }
   `
 
@@ -88,14 +95,18 @@ function getTypeScriptDateFnsModuleDefinition(submodule, fns) {
   }
 }
 
-function getTypeScriptDateFnsFPModuleDefinition(submodule, fns) {
+function getTypeScriptDateFnsFPModuleDefinition(
+  submodule,
+  fns,
+  constantsDefinitions
+) {
   const moduleName = `date-fns${submodule}/fp`
 
   const fnDefinitions = fns.map(getTypeScriptFPFnDefinition)
 
   const definition = formatBlock`
     declare module '${moduleName}' {
-      ${addSeparator(fnDefinitions, '\n')}
+      ${addSeparator(fnDefinitions.concat(constantsDefinitions), '\n')}
     }
   `
 
@@ -243,11 +254,16 @@ function generateTypescriptLocaleTyping(locale) {
   writeFile(`src/locale/${locale.code}/index.d.ts`, typingFile)
 }
 
-function generateTypeScriptTypings(fns, aliases, locales) {
+function generateTypeScriptTypings(fns, aliases, locales, constants) {
   const nonFPFns = fns.filter(fn => !fn.isFPFn)
   const fpFns = fns.filter(fn => fn.isFPFn)
+  const constantsDefinitions = constants.map(
+    c => `const ${c.name}: ${c.type.names.join(' | ')}`
+  )
 
-  const moduleDefinitions = [getTypeScriptDateFnsModuleDefinition('', nonFPFns)]
+  const moduleDefinitions = [
+    getTypeScriptDateFnsModuleDefinition('', nonFPFns, constantsDefinitions)
+  ]
     .concat(nonFPFns.map(getTypeScriptFnModuleDefinition.bind(null, '', '')))
     .concat(
       nonFPFns.map(getTypeScriptFnModuleDefinition.bind(null, '', '/index'))
@@ -258,7 +274,7 @@ function generateTypeScriptTypings(fns, aliases, locales) {
     .map(module => module.definition)
 
   const fpModuleDefinitions = [
-    getTypeScriptDateFnsFPModuleDefinition('', fpFns)
+    getTypeScriptDateFnsFPModuleDefinition('', fpFns, constantsDefinitions)
   ]
     .concat(
       fpFns.map(getTypeScriptFPFnModuleDefinition.bind(null, '', '', false))
@@ -276,7 +292,7 @@ function generateTypeScriptTypings(fns, aliases, locales) {
     .map(module => module.definition)
 
   const esmModuleDefinitions = [
-    getTypeScriptDateFnsModuleDefinition('/esm', nonFPFns)
+    getTypeScriptDateFnsModuleDefinition('/esm', nonFPFns, constantsDefinitions)
   ]
     .concat(
       nonFPFns.map(getTypeScriptFnModuleDefinition.bind(null, '/esm', ''))
@@ -292,7 +308,7 @@ function generateTypeScriptTypings(fns, aliases, locales) {
     .map(module => module.definition)
 
   const esmFPModuleDefinitions = [
-    getTypeScriptDateFnsFPModuleDefinition('/esm', fpFns)
+    getTypeScriptDateFnsFPModuleDefinition('/esm', fpFns, constantsDefinitions)
   ]
     .concat(
       fpFns.map(getTypeScriptFPFnModuleDefinition.bind(null, '/esm', '', true))
@@ -358,7 +374,12 @@ function generateTypeScriptTypings(fns, aliases, locales) {
 
   const globalInterfaceDefinition = formatBlock`
     interface dateFns {
-      ${addSeparator(nonFPFns.map(getTypeScriptInterfaceDefinition), '\n')}
+      ${addSeparator(
+        nonFPFns
+          .map(getTypeScriptInterfaceDefinition)
+          .concat(constants.map(c => `${c.name}: ${c.type.names.join(' | ')}`)),
+        '\n'
+      )}
     }
   `