prep release

Author: Alorel

.npmignore

@@ -0,0 +1,18 @@
+/.idea/
+/node_modules/
+/coverage/
+/.nyc_output/
+/package-lock.json
+/.env
+/src/
+/*.tgz
+/types/_Update.d.ts
+/dist/_transformSyncInternal.d.ts
+/test/
+/.travis.yml
+/.nycrc
+/mocha.opts
+/tsconfig.json
+/tsconfig.test.json
+/tslint.json
+/update-version.js

.travis.yml

@@ -31,22 +31,24 @@ env:
     - TS_NODE_CACHE_DIRECTORY=./node_modules/.cache/ts-node
     - TS_NODE_PROJECT=./tsconfig.test.json
 
-#stages:
-#  - Test
-#  - Stub
-#  - Stub2
-
-#jobs:
-#  include:
-#    - stage: Stub
-#      services: false
-#      node_js: *latestTested
-#      before_install: false
-#      after_success: echo bar
-#      script: echo foo
-#    - stage: Stub2
-#      services: false
-#      node_js: *latestTested
-#      before_install: false
-#      after_success: echo qux
-#      script: echo baz
+stages:
+  - Test
+  - name: &releaseStage Release
+    if: tag IS present
+
+jobs:
+  include:
+    - stage: *releaseStage
+      services: false
+      node_js: *latestTested
+      script: npm run build
+      after_success: false
+      before_deploy: node ./update-version.js
+      deploy:
+        - provider: npm
+          on:
+            tags: true
+          skip_cleanup: true
+          email: a.molcanovas@gmail.com
+          api_key:
+            secure: "D8D0XyBCa2HzM/tq9PrU8bYIp8sHaZCxYJhZOnyELJ+vPf39nKW1vyVa34jcOab1JVbXS/Y29vPtd03FGPXPRZABJcjkXxBNW9o7u4khDKqZ2Z/498gvSZAIpSNrQzBQNPzwM1WZ4Fit1FIG24lzLIHCrfFV6pPc+urC8C6IO10MUqkRhE0TfyouHCXQkd59oZL7u3pSY/LB70bId5Noq8Cmr2bloDIZFwy5bZq3Udm4WX/+tMiO9qTDcwfZGX0uFPwumFJw/xURGHmmrbn+qarbRDH6RNa2MHMgkime/f1vR1K9J+22m6MqpH0aZ30EaaUGsXuBNwDPSSTc2Y+9RQE6D5sTZzBdtpHKAXa0ACiCFte+x+SCypHBubquSU0gkO+CDBoohVFG4h7pocawsMMfR5+IOKnBxBmiwJC8QjUYislzkUL9TS/ZmW9lrab8PQSKlpiXXdEWkI4pDxQbF4fDG33aveCKw+geB0vqh8iTVQphqhBbp3elZMuKl/fsbkCPloIgjIb+d8M3r7UVYC0wM9N2/FMr5NVKFL1e4r9X1GcusS0X4itFvqwuKlBYM9d1LLn1vPUnETfFKrA+sKvoJVVCuvZUyzZ7MnBLZ17djwuCrp0jb3AF+DKZUH35SvRjiMldflaHvzv5J94s7251uhTeSPx4MLmB6iogMXM="

README.md

@@ -1,3 +1,155 @@
 # mongoose-transform-field-plugin
 
-[![Greenkeeper badge](https://badges.greenkeeper.io/Alorel/mongoose-transform-field-plugin.svg)](https://greenkeeper.io/)
+An automatic field transformation plugin for Mongoose 5. Any transformations are registered as `save`, `update` and `findOneAndUpdate` middleware.
+
+[![NPM link](https://nodei.co/npm/mongoose-transform-field-plugin.svg?compact=true)](https://www.npmjs.com/package/mongoose-transform-field-plugin)
+[![Build Status](https://travis-ci.org/Alorel/mongoose-transform-field-plugin.svg?branch=master)](https://travis-ci.org/Alorel/mongoose-transform-field-plugin)
+[![Coverage Status](https://coveralls.io/repos/github/Alorel/mongoose-transform-field-plugin/badge.svg?branch=master)](https://coveralls.io/github/Alorel/mongoose-transform-field-plugin?branch=master)
+[![Greenkeeper badge](https://badges.greenkeeper.io/Alorel/mongoose-transform-field-plugin.svg)](https://greenkeeper.io/)
+![Supports Node >= 6](https://img.shields.io/badge/Node-%3E=6.0.0-brightgreen.svg)
+![Supports Mongoose >= 5.0](https://img.shields.io/badge/Mongoose-%3E=5.0.0-brightgreen.svg)
+
+-----
+
+# Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Asynchronous transformation](#asynchronous-transformation)
+  - [Direct usage](#direct-usage)
+  - [Schema plugin usage](#schema-plugin-usage)
+- [Normalisation](#normalisation)
+- [Synchronous Transformations](#synchronous-transformations)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Asynchronous transformation
+
+## Direct usage
+
+```typescript
+import * as bcrypt from 'bcrypt';
+import * as mongoose from 'mongoose';
+import {AsyncTransform, MongooseTransformFieldPlugin} from 'mongoose-transform-field-plugin';
+
+const schema = new mongoose.Schema({
+  password: String
+});
+
+const transformer: AsyncTransform<string> = (pwd: string): Promise<string> => {
+  return bcrypt.hash(pwd, 12);
+};
+
+// Run as non-parallel Mongoose middleware by default
+MongooseTransformFieldPlugin.transformAsync(schema, 'password', transformer);
+
+// Run as non-parallel Mongoose middleware explicitly
+MongooseTransformFieldPlugin.transformAsync(schema, 'password', false, transformer);
+
+// Run as a parallel Mongoose middleware
+MongooseTransformFieldPlugin.transformAsync(schema, 'password', true, transformer);
+```
+
+## Schema plugin usage
+
+```typescript
+import * as bcrypt from 'bcrypt';
+import * as mongoose from 'mongoose';
+import {AsyncTransform, MongooseTransformFieldPlugin, TransformAsyncOptions} from 'mongoose-transform-field-plugin';
+
+const schema = new mongoose.Schema({
+  password: String
+});
+
+const transform: AsyncTransform<string> = (pwd: string): Promise<string> => {
+  return bcrypt.hash(pwd, 12);
+};
+
+// Run as non-parallel Mongoose middleware by default
+let config: TransformAsyncOptions<string> = {
+  field: 'password',
+  transformer: transform
+};
+schema.plugin(MongooseTransformFieldPlugin.transformAsync.plugin, config);
+
+// Run as non-parallel Mongoose middleware explicitly
+config = {
+  field: 'password',
+  parallel: false,
+  transformer: transform
+};
+schema.plugin(MongooseTransformFieldPlugin.transformAsync.plugin, config);
+
+// Run as a parallel Mongoose middleware
+config = {
+  field: 'password',
+  parallel: true,
+  transformer: transform
+};
+schema.plugin(MongooseTransformFieldPlugin.transformAsync.plugin, config);
+```
+
+# Normalisation
+
+This transforms accented characters from a string, trims it and makes it lowercase before storing it in another field.
+Useful if you want some basic search functionality.
+
+```typescript
+import * as mongoose from 'mongoose';
+import {MongooseTransformFieldPlugin} from 'mongoose-transform-field-plugin';
+
+const schema = new mongoose.Schema({
+  firstname: String,
+  firstname_normalised: {
+    select: false,
+    type: String
+  },
+  lastname: String,
+  lastname_normalised: {
+    select: false,
+    type: String
+  }
+});
+
+const fields = {
+  firstname: 'firstname_normalised', // firstname will be normalised into the firstname_normalised field
+  lastname: 'lastname_normalised' // lastname will be normalised into the lastname_normalised field
+};
+
+// Direct usage
+MongooseTransformFieldPlugin.normalise(schema, fields);
+
+// Plugin usage
+schema.plugin(MongooseTransformFieldPlugin.normalise.plugin, fields);
+```
+
+# Synchronous Transformations
+
+You should really use schema setters instead, but this is included for completeness' sake.
+
+```typescript
+import * as bcrypt from 'bcrypt';
+import * as mongoose from 'mongoose';
+import {MongooseTransformFieldPlugin, SyncTransform, TransformSyncOptions} from 'mongoose-transform-field-plugin';
+
+const schema = new mongoose.Schema({
+  password: String
+});
+
+const transform: SyncTransform<string> = (pwd: string): string => {
+  return bcrypt.hashSync(pwd, 12);
+};
+
+// Direct usage
+MongooseTransformFieldPlugin.transformSync(schema, 'password', transform);
+
+// Plugin usage
+const conf: TransformSyncOptions<string> = {
+  field: 'password',
+  transformer: transform
+};
+
+schema.plugin(MongooseTransformFieldPlugin.transformSync.plugin, conf);
+```

package.json

@@ -1,14 +1,15 @@
 {
   "name": "mongoose-transform-field-plugin",
   "version": "1.0.0",
-  "description": "Easily apply field transformation middleware",
-  "main": "dist/plugin.js",
+  "description": "An automatic field transformation plugin for Mongoose 5",
+  "main": "dist/index.js",
   "engines": {
     "node": ">=6.0"
   },
   "scripts": {
     "clean": "rimraf dist",
     "build": "npm run clean && tsc",
+    "doctoc": "doctoc --github README.md",
     "typecheck": "tsc --noEmit",
     "typecheck:watch": "npm run typecheck -- --watch",
     "lint": "tslint -p ./tsconfig.test.json -s node_modules/custom-tslint-formatters/formatters -t grouped",
@@ -57,6 +58,7 @@
     "chai": "^4.1.2",
     "coveralls": "^3.0.0",
     "custom-tslint-formatters": "^2.1.1",
+    "doctoc": "^1.3.0",
     "env-cmd": "^7.0.0",
     "lodash": "^4.17.5",
     "mocha": "^5.0.0",

src/normalise.ts

@@ -57,7 +57,7 @@ namespace normalise {
    * @param fields Fields to normalise. The keys should be the source, non-normalised fields while the values will hold
    * the normalised output.
    */
-  export function plugin(schema: Schema, fields: { [sourceField: string]: string }): void {
+  export function plugin(schema: Schema, fields?: any): void {
     normalise(schema, fields);
   }
 }

src/transformAsync.ts

@@ -9,19 +9,22 @@ import {AsyncTransform} from '../types/Transform';
  * @param field Field to apply the transformation to
  * @param transformer The transformation function. This should return a Promise.
  */
-function transformAsync(schema: Schema, field: string, transformer: AsyncTransform<any>): void;
+function transformAsync<T = any>(schema: Schema, field: string, transformer: AsyncTransform<T>): void;
 /**
  * Perform an asynchronous transformation on the given field
  * @param schema Schema to apply the transformation to
  * @param field Field to apply the transformation to
  * @param parallel Whether or not this should run as parallel middleware
  * @param transformer The transformation function. This should return a Promise.
  */
-function transformAsync(schema: Schema, field: string, parallel: boolean, transformer: AsyncTransform<any>): void;
-function transformAsync(schema: Schema,
-                        field: string,
-                        parallelOrTransformer: boolean | AsyncTransform<any>,
-                        possibleTransformer?: AsyncTransform<any>): void {
+function transformAsync<T = any>(schema: Schema,
+                                 field: string,
+                                 parallel: boolean,
+                                 transformer: AsyncTransform<T>): void;
+function transformAsync<T>(schema: Schema,
+                           field: string,
+                           parallelOrTransformer: boolean | AsyncTransform<T>,
+                           possibleTransformer?: AsyncTransform<T>): void {
   if (!schema) {
     throw new TypeError('Schema is required');
   } else if (typeof field !== 'string' || !field) {
@@ -115,7 +118,7 @@ function transformAsync(schema: Schema,
 
 namespace transformAsync {
   /** Options for applying the plugin as a schema plugin */
-  export interface TransformAsyncOptions {
+  export interface TransformAsyncOptions<T = any> {
     /** Field to apply the transformation to */
     field: string;
     /**
@@ -124,20 +127,25 @@ namespace transformAsync {
      */
     parallel?: boolean;
     /** The transformation function. This should return a Promise. */
-    transformer: AsyncTransform<any>;
+    transformer: AsyncTransform<T>;
   }
 
   /**
    * Perform an asynchronous transformation on the given field
    * @param schema Schema to apply the transformation to
    * @param options Configuration
    */
-  export function plugin(schema: Schema, options: TransformAsyncOptions): void {
+  export function plugin(schema: Schema, options?: any): void {
     if (!options) {
       throw new TypeError('Options are required');
     }
 
-    transformAsync(schema, options.field, !!options.parallel, options.transformer);
+    transformAsync(
+      schema,
+      (<TransformAsyncOptions>options).field,
+      !!<any>(<TransformAsyncOptions>options).parallel,
+      (<TransformAsyncOptions>options).transformer
+    );
   }
 }
 

src/transformSync.ts

@@ -8,7 +8,7 @@ import {transformSyncInternal} from './_transformSyncInternal';
  * @param field Field to apply the transformation to
  * @param transformer The transformation function.
  */
-function transformSync(schema: Schema, field: string, transformer: SyncTransform<any>): void {
+function transformSync<T = any>(schema: Schema, field: string, transformer: SyncTransform<T>): void {
   if (typeof field !== 'string' || !field) {
     throw new TypeError('The field must be a non-empty string');
   } else if (typeof transformer !== 'function') {
@@ -25,24 +25,24 @@ function transformSync(schema: Schema, field: string, transformer: SyncTransform
 
 namespace transformSync {
   /** Synchronous transformer options */
-  export interface TransformSyncOptions {
+  export interface TransformSyncOptions<T = any> {
     /** Field to apply the transformation to */
     field: string;
     /** The transformation function. */
-    transformer: SyncTransform<any>;
+    transformer: SyncTransform<T>;
   }
 
   /**
    * Perform a synchronous transformation on the given field
    * @param schema Schema to apply the transformation to
    * @param options Configuration
    */
-  export function plugin(schema: Schema, options: TransformSyncOptions): void {
+  export function plugin(schema: Schema, options?: any): void {
     if (!options) {
       throw new Error('Options are required');
     }
 
-    transformSync(schema, options.field, options.transformer);
+    transformSync(schema, (<TransformSyncOptions>options).field, (<TransformSyncOptions>options).transformer);
   }
 }
 

types/Transform.d.ts

@@ -1,4 +1,6 @@
 import {Thenable} from './Thenable';
 
+/** A synchronous transformation function */
 export type SyncTransform<T = any> = (val: T) => T;
+/** An asynchronous transformation function */
 export type AsyncTransform<T = any> = (val: T) => Thenable<T>;

types/_Update.d.ts

@@ -1,3 +1,4 @@
+/** @internal */
 export interface Update {
   $set: any;
   $setOnInsert: any;

update-version.js

@@ -0,0 +1,9 @@
+const fs = require('fs');
+const {join} = require('path');
+
+const path = join(__dirname, 'README.md');
+let contents = fs.readFileSync(path, 'utf8');
+const version = require('./package').version;
+
+contents = contents.replace(/\?branch=master/g, `?branch=${version}`);
+fs.writeFileSync(path, contents);