doublescore - npm Package Compare versions

Comparing version 0.3.7 to 1.0.0

package.json

 {
-	"name": "doublescore",
-	"description": "Utility functions for managing data structures and measurement.",
-	"author": "Anthony Hildoer <[e-mail]>",
-	"version": "0.3.7",
-	"repository": {
-		"type": "git",
-		"url": "git://github.com/bluerival/doublescore.git"
-	},
-	"scripts": {
-		"test": "node_modules/mocha/bin/mocha -b -u bdd test/default"
-	},
-	"keywords": [
-		"object",
-		"array",
-		"clone",
-		"mixin",
-		"isObject",
-		"isArray"
-	],
-	"devDependencies": {
-		"async": "1.5.2",
-		"mocha": "2.3.4"
-	},
-	"engines": {
-		"node": ">=0.10.0"
-	},
-	"license": "MIT"
+  "name": "doublescore",
+  "description": "Utility functions for managing data structures and measurement.",
+  "author": "Anthony Hildoer <[e-mail]>",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/bluerival/doublescore.git"
+  },
+  "scripts": {
+    "prepublish": "npm run build",
+    "build": "mkdir dist; rm -rf dist/*; node_modules/.bin/tsc",
+    "test": "node_modules/mocha/bin/mocha -r ts-node/register --bail -u bdd --exit test/main.ts",
+    "test-watch": "node_modules/mocha/bin/mocha -r ts-node/register --bail -u bdd --exit --watch --extension ts test/main.ts"
+  },
+  "keywords": [
+    "object",
+    "iterate",
+    "array",
+    "clone",
+    "mixin",
+    "isObject",
+    "isArray",
+    "timer",
+    "getTypes",
+    "typeof"
+  ],
+  "devDependencies": {
+    "@types/async": "3.0.1",
+    "@types/glob": "7.1.1",
+    "@types/mocha": "5.2.7",
+    "@types/node": "12.7.1",
+    "@types/rimraf": "2.0.2",
+    "async": "3.1.0",
+    "glob": "7.1.4",
+    "mocha": "6.2.0",
+    "rimraf": "2.6.3",
+    "ts-node": "8.3.0",
+    "tslint": "5.18.0",
+    "typescript": "3.5.3"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=10.0.0"
+  },
+  "license": "MIT"
 }

README.md

@@ -1,60 +0,107 @@
-doublescore
-====================
+# doublescore
 
-A natively written, no external dependency utility library.
+A natively (TypeScript native at least) written, no external dependency utility library.
 
+# Version 1.0.0 Changes
 
-These are the available utility functions.
+The native code for doublescore has moved to TypeScript. JavaScript libraries can still use this library as always. But, 
+TypeScript based libraries will now have a much easier time using it. With the exception of one removed feature set, 
+DoubleScore should work in place for both JS and TS based projects. Nevertheless, TypeScript transpiling is a big change
+so we bumped the major version to 1, and also officially pushed it over the line to full blown production grade.
 
+### Removed Features 
+ 
+The following features were removed in 1.0.0:
 
-iterate()
+- Close: All close functionality for managing callback SLAs have been removed. This was a non-used feature, and is 
+slightly too specific for the overall purposes of DoubleScore. DoubleScore aims to be a utility for managing data 
+structures. Managing callbacks is not within that scope.
 
+
+# Usage 
+
+## Including the Library
+
+### TypeScript
+```typescript
+import * as  __  from 'doublescore';
+
+```
+
+### JavaScript
 ```javascript
+const __ = require( 'doublescore' );
+```
 
-var __ = require( 'doublescore' );
+These are the available utility functions.
 
-__([0, { one: 1}, [2, 3] ]).iterate(function( value, index) {
-	/** is called 4 times with the params value/index:
-	 * 0/[0]
-	 * 1/[1,'one']
-	 * 2/[2, 0]
-	 * 3/[2, 1]
+
+
+## iterate()
+
+Iterate enumerates the leaves of an n-dimensional data structure in depth first order. The first parameter will be the 
+value of the leaf, the second parameter will be the index path of the leaf. This is very similar to Array.forEach(). The
+only difference is that iterate passes an array for index because the input can be n-dimensional, with nested objects.
+
+Note that you can pass multiple objects to the method so iterate is actually traversing the arguments "array", and the 
+index to that is the first index field.
+
+```typescript
+
+__( [ 0, { one: 1 }, [ 2, 3 ] ], [ 4, 5 ] ).iterate( ( value, path ) => {
+	/** is called 4 times with the params value/path:
+	 * 0/[0, 0]
+	 * 1/[0, 1,'one']
+	 * 2/[0, 2, 0]
+	 * 3/[0, 2, 1]
+	 * 4/[1, 0]
+	 * 5/[1, 1]
 	 */
+} );
 
-});
+__( ['one', 'two', 'three' ], [ 'four', 'five' ] ).iterate( ( value, path ) => {
+	/** is called 5 times with the params value/path:
+	 * 'one'/[0, 0]
+	 * 'two'/[0, 1]
+	 * 'three'/[0, 2]
+	 * 'four'/[1, 0]
+	 * 'five'/[1, 1]
+	 */
+} );
 
 ```
 
+## iterate.flatten()
 
-close() 
+Flatten is kin to Iterate, hence the chaining. Flatten is basically the result of listing all values returned by iterate 
+and ignoring path. For example, consider the output of the following code.
 
-```javascript
+```typescript
 
-var __ = require( 'doublescore' );
+const values = __.iterate.flatten(
+            [ 0, 1, 2, 3 ],
+            [ 'a', 'b', 'c' ],
+            [ { one: 'two', three: -3, four: false }, 'b', 'c' ],
+            [],
+            [ -1, null ],
+            [ 'a', [ false, true, -1, null ], 'c' ]
+          );
 
-close = __( {
-	timeout: 30000
-} ).close()
+console.log( values );
 
-function doSomething( params, done ) {
+/**
+  * Outputs:
+  * [ 0, 1, 2, 3, 'a', 'b', 'c', 'two', -3, false, 'b', 'c', -1, null, 'a', false, true, -1, null, 'c' ]
+*/
 
-	// ensure done is called within 30 seconds, multiple calls ignored
-	done = close( done );
-	
-	someIoCall( params, done );
-
-}
 ```
 
-Returns a function used to generate callbacks with a service level of max calls and minimum TTL until callback errors
 
 
-isObject() 
+## isObject() 
 
 Will return TRUE for anything that is typeof object, is not an Array, and is not NULL.
 
-```javascript
 
-var __ = require( 'doublescore' );
-
+```typescript
 __.isObject( new Date() ); // true
@@ -67,2 +114,4 @@ __.isObject( {} ); // true
 __.isObject( true ); // false
+__.isObject( false ); // false
+__.isObject( [] ); // false
 
@@ -72,44 +121,99 @@ ```
 
-getType() 
+## getType() 
 
-Will return 'null' for NULL, 'array' for an Array, 'float' for a non-integer number, 'integer' for an integer number, and typeof result for all else.
+This expands on the resolution of the native ```typeof <var>``` operation. 
 
+```typescript
 
+__.getType( null ); // 'null'
+__.getType( undefined ); // 'undefined'
+__.getType( [] ); // 'array'
+__.getType( new Array() ); // 'array'
+__.getType( new Date() ); // 'date'
+__.getType( new RegExp( 'anything' ) ); // 'regex'
+__.getType( parseInt('not-a-number') ); // 'not-a-number'
+__.getType( Math.pow( 10, 1000 ) ); // 'infinity'
+__.getType( 1.1 ); // 'float'
+__.getType( -1.1 ); // 'float'
+__.getType( 1 ); // 'integer'
+__.getType( 0 ); // 'integer'
+__.getType( 0.0 ); // 'integer' What?! I know, this doesn't make sense but after compiling Javascript sees this the same as 0
+__.getType( -1 ); // 'integer'
+__.getType( 1n ); // 'integer' Technically a BigInt, but that's not official, so not supporting it yet
+
+// All other values not covered by one of the cases above and falls back to returning typeof <var>
+
+```
+
+
+
 clone() 
 
-Will return a distinct copy of the object it was called from. Date objects are cloned, arrays and objects are recursively cloned down 100 levels max and all else is just passed through.
+Will return a distinct copy of the object it was called from. Depending on the value type it is handled differently.
 
+Primitives are natively copied/cloned anytime you assign them or pass them to a method/function. This is the case for 
+strings, numbers, boolean, null, etc.
 
+Simple objects and arrays are recursively cloned. 
+
+Date objects are cloned. 
+
+Everything else is passed through directly. If is is natively copied/cloned by assignment, it will be cloned, otherwise
+it will be carried over to the destination. Functions, for example, will be copied to the destination.
+
+The performance of this is better than JSON.parse( JSON.stringify( thing ) ).
+
+```typescript
+
+function goodFunctionalProgramming( obj: SomeType ) {
+  
+  obj = __.clone( obj );
+  
+  // modify obj
+  
+  return obj;
+  
+}
+
+```
+
 mixin() 
 
-Applies clone() to params and then recursively mixes all values into default. If types do not match, params type is taken. mixin() accepts an arbitrary number of arguments, they will be mixed in from left to right.
+Applies clone() to params and then recursively mixes all values into default. If types do not match, params type is 
+taken. mixin() accepts an arbitrary number of arguments, they will be mixed in from left to right. That is, if the same
+path exists in two arguments, the furthest right argument will have its value kept. 
 
-```javascript
+This method is an excellent way to ensure defaults or overrides recursively.
 
-var __ = require( 'doublescore' );
+```typescript
 
-function doSomething  ( params, done ) {
+function doSomething  ( params ) {
 
-    // sets defaults recursively
-	params = __( {
-		deep: [
-			{
-				merge: 'on this default object of'
-			}
-		],
-		strings: {
-			objects: 'and',
-			numbers: 1.5
-		},
-		and: null,
-		boolean: true,
-		etc: [ false, false ],
-		from: 'params'
-	} ).mixin( params );
+  const defaults = {
+    deep: [
+      {
+        merge: 'on this default object of'
+      }
+    ],
+    strings: {
+      objects: 'and',
+      numbers: 1.5
+    },
+    and: null,
+    etc: [ false, false ],
+    from: 'params'
+  };
+  
+  const overrides = {
+    boolean: false
+  };
+
+  // sets defaults and overrides recursively
+	params = __( defaults ).mixin( params, overrides );
 	
-	//... 
-	
-	done();
 
+	// handle params... 
+
 }
+
 ```
@@ -119,25 +223,47 @@
 
-Will return a function that will track time deltas with 1ms resolution and < 0.1% error on average. The returned function accepts a single parameter: reset, which if true will reset the timer, returning the last interval
+Will return a function that will track time deltas with 1ms resolution and < 0.5% error on average. The returned 
+function accepts a single parameter: reset, which if true will reset the timer, returning the last interval.
 
-NOTE: timer() is experimental. 0.5% margin of error for both precision and accuracy at best, probably closer to 1% for most intervals of time. However, deviance is constant regardless of actual time interval measured. Thus, error rates for higher intervals (> 100ms) will be considerably lower than those for short intervals (< 50ms).
+Note: For intervals of < 10ms, timer() is likely not accurate enough. If you want to experimentally measure the time of 
+something that takes <10ms to run once, you should run it N times, measuring total execution time, then divide by N. N
+should be something large like 100.
  
+```typescript
 
-Usage
-====================
+const timer = __.timer();
 
-The usage for doublescore is patterned after other utility libraries like underscore. BUT, it is not interchangeable.
+// wait 100ms
 
+timer(); // returns 100 +- 0.5%
 
-More examples
-=============
+// wait 50ms
 
-Please see the test cases in test/default.js for extensive examples of all supported use cases.
+timer(); // returns 150 +- 0.5%
 
+// wait 300ms
 
-License
-====================
+timer( true ); // returns 450 +- 0.5%
 
+// wait 200ms
+
+timer(); // returns 200 +- 0.5%
+
+// wait 175ms
+
+timer(); // returns 375 +- 0.5%
+
+
+```
+
+# More examples
+
+Please see the test cases in test/* for extensive examples of all supported use cases. Test cases are available in the
+Git repo for this code base.
+
+
+# License
+
 (The MIT License)
 
-Copyright (c) 2016 BlueRival Software <[e-mail]>
+Copyright (c) 2019 BlueRival Software <[e-mail]>
 
@@ -144,0 +270,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

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

Number of package files

21

increased by5%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

278

increased by82.89%

Worsened metrics

Total package byte prevSize

33873

decreased by-34.77%

Dev dependency count

12

increased by500%

Lines of code

410

decreased by-73.67%

Number of medium supply chain risk alerts

2

increased byInfinity%

No dependency changes