adts - npm Package Compare versions

Comparing version 0.1.1 to 0.1.2

adts.d.ts

@@ -38,3 +38,3 @@ declare module "adts" {
          * [mutable, chainable] */
-        _addArray(elements: string[]): Set;
+        _addArray(elements?: string[]): Set;
         /** Add all elements from another Set.
@@ -41,0 +41,0 @@ * [mutable, chainable] */

index.js

@@ -76,2 +76,3 @@ /**
     Set.prototype._addArray = function (elements) {
+        if (elements === void 0) { elements = []; }
         for (var i = 0, element; (element = elements[i]) !== undefined; i++) {
@@ -191,2 +192,3 @@ this._element_object[element] = true;
         var prototype_set = sets[0];
+        // use a for loop to allow immediate return
         for (var i = 1, other; (other = sets[i]) !== undefined; i++) {
@@ -193,0 +195,0 @@ var prototype_other_equal = keysEqual(prototype_set._element_object, other._element_object);

package.json

 {
   "name": "adts",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Abstract Data Types in TypeScript",
@@ -24,4 +24,4 @@ "keywords": [
   "devDependencies": {
-    "TypeScript": "*",
-    "mocha": "*"
+    "TypeScript": "1.3.0",
+    "mocha": "~2.1.0"
   },
@@ -28,0 +28,0 @@ "scripts": {

README.md

@@ -13,8 +13,68 @@ # adts
 
-## Example import
+## Example import configuration
 
+If you have a **plain JavaScript** Node.js project, imports work as usual.
+
+Download the `adts` package from the npm registry:
+
+    npm install --save adts
+
+Then require and use:
+
+    var adts = require('adts');
+
+    var primes = new adts.Set([2, 3, 5, 7, 11, 13, 17, 19, 23]);
+    var even = new adts.Set([2, 4, 6, 8, 10, 12, 14, 16]);
+    var even_primes = adts.Set.intersection([even, primes]);
+    console.log('primes that are even: %j', even_primes);
+    // prints 'primes that are even: ["2"]'
+
+
+If you have a **TypeScript** Node.js project, using [`tsd`](http://definitelytyped.org/tsd/) and [DefinitelyTyped](http://definitelytyped.org/) for most of your dependencies, imports are straightforward, but not idiomatic:
+
+Download the `adts` package from the npm registry.
+
+    npm install --save adts
+
+Assuming `tsd` is using the defaults, the aggregate `d.ts` file will be in `typings/tsd.d.ts`. Open that file, and add the following line:
+
     /// <reference path="../node_modules/adts/adts.d.ts"/>
+
+(The `tsd` documentation states that `tsd link` will handle that, but `tsd link` isn't actually a `tsd` command.)
+
+Now importing the aggregate file will import the `adts` type declarations along with it.
+Suppose you want to use the `adts` module in `index.ts`:
+
+    /// <reference path="typings/tsd.d.ts"/>
     import adts = require('adts');
 
+    var primes = new adts.Set([2, 3, 5, 7, 11, 13, 17, 19, 23]);
+    var even = new adts.Set([2, 4, 6, 8, 10, 12, 14, 16]);
+    var even_primes = adts.Set.intersection([even, primes]);
+    console.log('primes that are even: %j', even_primes);
 
+Now try to compile:
+
+    tsc -m commonjs index.ts
+
+Which produces the error message:
+
+    index.ts(4,27): error TS2345: Argument of type 'number[]' is not assignable to
+      parameter of type 'string[]'. Type 'number' is not assignable to type 'string'.
+    index.ts(5,25): error TS2345: Argument of type 'number[]' is not assignable to
+      parameter of type 'string[]'. Type 'number' is not assignable to type 'string'.
+
+It turns out `adts.Set` only accepts strings in its constructor, since that's how it stores elements internally.
+The plain JS version automatically coerced them to strings, which is fine, but something we need to care about if we're using TypeScript.
+Rewrite the sets like so:
+
+    var primes = new adts.Set(['2', '3', '5', '7', '11', '13', '17', '19', '23']);
+    var even = new adts.Set(['2', '4', '6', '8', '10', '12', '14', '16']);
+
+Now recompile (`tsc -m commonjs index.ts`) and run:
+
+    node index.js
+    // prints 'primes that are even: ["2"]'
+
+
 ## TODO
@@ -39,4 +99,34 @@
 
+## Build notes
+
+TypeScript does not make inter-project modularity easy. Here are some features that I'd like [`tsc`](https://github.com/Microsoft/TypeScript) to support.
+
+1. Generate a `.d.ts` type declaration for use by 3rd-party modules.
+
+  As it stands, I'm not sure what the point of the declaration file is, since if you're generating a declaration file that only allows TypeScript-powered imports, you have to TypeScript-import the original modules as well, which `tsc` is then obliged to compile.
+
+  Fixing this can be pretty simple for a small project: `sed 's/declare module adts/declare module "adts"/g'`
+
+2. Merge module declarations in the generated `.d.ts` file.
+
+  TypeScript (as least v1.1) does not like having multiple external module declarations in one file, e.g., 'module "adts" { ... } module "adts" { } ...'. Otherwise, it's quite happy at merging interfaces and modules, but only reads one external module declaration when there are multiple. (Maybe this is fixed in v1.3?)
+
+3. Export a specific module in the generated `.d.ts` file, and expose that module at root level in the generated `.js` file(s).
+
+  In a typical Node.js module, often the only place the module name shows up is in the `package.json` and documentation. I like using namespaces, but TypeScript's compiler does not use them in a way that plays nice with Node.js's import idioms.
+
+
+### Implementation hacks
+
+The [Makefile](Makefile) demonstrates how I've hacked together support for these features, at least for this admittedly simplistic project.
+
+* All JavaScript code is exported in a single `index.js` file.
+* All type declarations are exported in `adts.d.ts`.
+  This filename is determined by the Makefile, not the project structure or TypeScript namespaces.
+* I can add TypeScripts files to `src/`, and these will automatically get picked up by the make process.
+  (But adding files to subdirectories would require further hacks.)
+
+
 ## License
 
 Copyright 2014-2015 Christopher Brown. [MIT Licensed](http://opensource.org/licenses/MIT).

test/set.js

@@ -0,1 +1,2 @@
+/*jslint node: true */ /*globals describe, it */
 var adts = require('../');
@@ -2,0 +3,0 @@ var assert = require('assert');

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

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

Improved metrics

Total package byte prevSize

55715

increased by8.33%

Lines of code

775

increased by0.91%

Number of lines in readme file

131

increased by219.51%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes