caching-transform - npm Package Compare versions

Comparing version 0.0.4 to 1.0.0

index.js

 'use strict';
 
 var mkdirp = require('mkdirp');
-var crypto = require('crypto');
+var md5Hex = require('md5-hex');
 var fs = require('fs');
@@ -9,12 +9,4 @@ var path = require('path');
 
-function getHash(input, salt) {
-	return crypto
-		.createHash('md5')
-		.update(input, 'utf8')
-		.update(salt || '', 'utf8')
-		.digest('hex');
-}
-
 function defaultHash(input, additionalData, salt) {
-	return getHash(input, salt);
+	return md5Hex([input, salt || '']);
 }
@@ -40,4 +32,5 @@
 	var hashFn = opts.hash || defaultHash;
+	var encoding = opts.encoding === 'buffer' ? undefined : opts.encoding || 'utf8';
 
-	function transform(input, additionalData, hash) {
+	function transform(input, metadata, hash) {
 		if (!created) {
@@ -52,21 +45,21 @@ if (!cacheDirCreated && !disableCache) {
 		}
-		return transformFn(input, additionalData, hash);
+		return transformFn(input, metadata, hash);
 	}
 
-	return function (input, additionalData) {
-		if (shouldTransform && !shouldTransform(input, additionalData)) {
+	return function (input, metadata) {
+		if (shouldTransform && !shouldTransform(input, metadata)) {
 			return input;
 		}
 		if (disableCache) {
-			return transform(input, additionalData);
+			return transform(input, metadata);
 		}
 
-		var hash = hashFn(input, additionalData, salt);
+		var hash = hashFn(input, metadata, salt);
 		var cachedPath = path.join(cacheDir, hash + ext);
 
 		try {
-			return fs.readFileSync(cachedPath, 'utf8');
+			return fs.readFileSync(cachedPath, encoding);
 		} catch (e) {
-			var result = transform(input, additionalData, hash);
-			writeFileAtomic.sync(cachedPath, result);
+			var result = transform(input, metadata, hash);
+			writeFileAtomic.sync(cachedPath, result, encoding);
 			return result;
@@ -78,2 +71,1 @@ }
 module.exports = wrap;
-module.exports.getHash = getHash;

package.json

 {
   "name": "caching-transform",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "description": "Wraps a transform and provides caching",
@@ -31,2 +31,3 @@ "license": "MIT",
   "dependencies": {
+    "md5-hex": "^1.2.0",
     "mkdirp": "^0.5.1",
@@ -33,0 +34,0 @@ "write-file-atomic": "^1.1.4"

readme.md

@@ -20,14 +20,17 @@ # caching-transform [![Build Status](https://travis-ci.org/jamestalmage/caching-transform.svg?branch=master)](https://travis-ci.org/jamestalmage/caching-transform) [![Coverage Status](https://coveralls.io/repos/jamestalmage/caching-transform/badge.svg?branch=master&service=github)](https://coveralls.io/github/jamestalmage/caching-transform?branch=master)
 
-cachingTransform({
+const transform = cachingTransform({
   cacheDir: '/path/to/cache/directory',
   salt: 'hash-salt',
-  transform: (input, additionalData, hash) => {
-    // ...
+  transform: (input, metadata, hash) => {
+    // ... expensive operations ...
     return transformedResult;
   }
 });
+
+transform('some input for transpilation')
+// => fetch from the cache,
+//    or run the transform and save to the cache if not found there
 ```
 
 
-
 ## API
@@ -40,3 +43,3 @@
  - `input` a string to be transformed
- - `additionalData` an arbitrary data object.
+ - `metadata` an arbitrary data object.
 
@@ -49,6 +52,6 @@ Both arguments are passed to the wrapped transform. Results are cached in the cache directory using an `md5` hash of `input` and an optional `salt` value. If a cache entry already exist for `input`, the wrapped transform function will never be called.
 
-Type: `string`
+Type: `string`, or `buffer`
 Default: `empty string`
 
-A string that uniquely identifies your transform, a typical salt value might be the concatenation of the module name of your transform and its version':
+A value that uniquely identifies your transform:
 
@@ -60,13 +63,13 @@ ```js
 
-Including the package version in the salt ensures existing cache entries will be automatically invalidated when you bump the version of your transform. If your transform relies on additional dependencies, and the transform output might change as those dependencies update, then your salt should incorporate the versions of those dependencies as well.
+Including the version in the salt ensures existing cache entries will be automatically invalidated when you bump the version of your transform. If your transform relies on additional dependencies, and the transform output might change as those dependencies update, then your salt should incorporate the versions of those dependencies as well.
 
 ##### transform
 
-Type: `Function(input: string, additionalData: *, hash: string): string`  
+Type: `Function(input: string|buffer, metadata: *, hash: string): string|buffer`  
 
- - `input`: The string to be transformed. passed through from the wrapper.
- - `additionalData`: An arbitrary data object passed through from the wrapper. A typical value might be a string filename.
- - `hash`: The salted hash of `input`. Useful if you intend to create additional cache entries beyond the transform result (i.e. `nyc` also creates cache entries for source-map data). This value is not available if the cache is disabled, if you still need it, it can be computed via `cachingTransform.getHash(input, salt)`.
+ - `input`: The value to be transformed. It is passed through from the wrapper.
+ - `metadata`: An arbitrary data object passed through from the wrapper. A typical value might be a string filename.
+ - `hash`: The salted hash of `input`. Useful if you intend to create additional cache entries beyond the transform result (i.e. `nyc` also creates cache entries for source-map data). This value is not available if the cache is disabled, if you still need it, the default can be computed via [`md5Hex([input, salt])`](https://www.npmjs.com/package/md5-hex).
 
-The transform function should return a `string` containing the result of transforming `input`.
+The transform function will return a `string` (or Buffer if `encoding === 'buffer'`) containing the result of transforming `input`.
 
@@ -79,2 +82,15 @@ ##### factory
 
+A typical usage would be to prevent eagerly `require`ing expensive dependencies like Babel:
+
+```js
+function factory() {
+  // Using the factory function, you can avoid loading Babel until you are sure it is needed. 
+  var babel = require('babel-core');
+  
+  return function (code, metadata) {
+    return babel.transform(code, {filename: metadata.filename, plugins: [/* ... */]});
+  };
+}
+```
+
 ##### cacheDir
@@ -95,6 +111,6 @@
 
-Type: `Function(input: string, additonalData: *)`
+Type: `Function(input: string|buffer, additonalData: *)`
 Default: `always transform`
 
-A function that examines `input` and `additionalData` to determine whether the transform should be applied. Returning `false` means the transform will not be applied and `input` will be returned unmodified.
+A function that examines `input` and `metadata` to determine whether the transform should be applied. Returning `false` means the transform will not be applied and `input` will be returned unmodified.
  
@@ -106,6 +122,21 @@ ##### disableCache
 
-If `true`, the cache is ignored and the transform is used every time regardless of cache contents. 
+If `true`, the cache is ignored and the transform is used every time regardless of cache contents.
+ 
+##### hash
 
+Type: `Function(input: string|buffer, metadata: *, salt: string): string`
+
+Provide a custom hashing function for the given input. The default hashing function does not take the `metadata` into account:
+
+> [`md5Hex([input, salt])`](https://www.npmjs.com/package/md5-hex)
+
+##### encoding
+
+Type: `string`
+Default: `utf8`
+
+The encoding to use when writing to / reading from the filesystem. If set to `"buffer"`, then buffers will be returned from the cache instead of strings.
+
 ## License
 
 MIT © [James Talmage](http://github.com/jamestalmage)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

9103

increased by11.42%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

136

increased by29.52%

Worsened metrics

Dependency count

3

increased by50%

Lines of code

58

decreased by-10.77%

Dependency changes

• + Addedmd5-hex@^1.2.0

• + Addedmd5-hex@1.3.0(transitive)

• + Addedmd5-o-matic@0.1.1(transitive)