jsii - npm Package Compare versions

Comparing version 0.7.0 to 0.7.1

CHANGELOG.md

@@ -6,2 +6,9 @@ # Change Log
 
+<a name="0.7.1"></a>
+## [0.7.1](https://github.com/awslabs/jsii/compare/v0.7.0...v0.7.1) (2018-08-28)
+
+### Features
+
+* **jsii:** Add check against downgrading properties to readonly ([#201](https://github.com/awslabs/jsii/issues/201)) ([f60b0ac](https://github.com/awslabs/jsii/commit/f60b0ace014e8e96090ead808436b1ce0cb6b1e8))
+
 <a name="0.7.0"></a>
@@ -8,0 +15,0 @@ # [0.7.0](https://github.com/awslabs/jsii/compare/v0.6.4...v0.7.0) (2018-08-21)

lib/version.js

 "use strict";
-// Generated at 2018-08-22T16:05:34Z by generate.sh
+// Generated at 2018-08-28T13:12:55Z by generate.sh
 Object.defineProperty(exports, "__esModule", { value: true });
 /** The qualified version number for this JSII compiler. */
 // tslint:disable-next-line:no-var-requires
-exports.VERSION = `${require('../package.json').version.replace(/\+[0-9a-f]+$/, '')} (build 0961b48)`;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmVyc2lvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbInZlcnNpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLG1EQUFtRDs7QUFFbkQsMkRBQTJEO0FBQzNELDJDQUEyQztBQUM5QixRQUFBLE9BQU8sR0FBRyxHQUFHLE9BQU8sQ0FBQyxpQkFBaUIsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsY0FBYyxFQUFFLEVBQUUsQ0FBQyxrQkFBa0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdlbmVyYXRlZCBhdCAyMDE4LTA4LTIyVDE2OjA1OjM0WiBieSBnZW5lcmF0ZS5zaFxuXG4vKiogVGhlIHF1YWxpZmllZCB2ZXJzaW9uIG51bWJlciBmb3IgdGhpcyBKU0lJIGNvbXBpbGVyLiAqL1xuLy8gdHNsaW50OmRpc2FibGUtbmV4dC1saW5lOm5vLXZhci1yZXF1aXJlc1xuZXhwb3J0IGNvbnN0IFZFUlNJT04gPSBgJHtyZXF1aXJlKCcuLi9wYWNrYWdlLmpzb24nKS52ZXJzaW9uLnJlcGxhY2UoL1xcK1swLTlhLWZdKyQvLCAnJyl9IChidWlsZCAwOTYxYjQ4KWA7XG4iXX0=
+exports.VERSION = `${require('../package.json').version.replace(/\+[0-9a-f]+$/, '')} (build 8b7682c)`;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmVyc2lvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbInZlcnNpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLG1EQUFtRDs7QUFFbkQsMkRBQTJEO0FBQzNELDJDQUEyQztBQUM5QixRQUFBLE9BQU8sR0FBRyxHQUFHLE9BQU8sQ0FBQyxpQkFBaUIsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsY0FBYyxFQUFFLEVBQUUsQ0FBQyxrQkFBa0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdlbmVyYXRlZCBhdCAyMDE4LTA4LTI4VDEzOjEyOjU1WiBieSBnZW5lcmF0ZS5zaFxuXG4vKiogVGhlIHF1YWxpZmllZCB2ZXJzaW9uIG51bWJlciBmb3IgdGhpcyBKU0lJIGNvbXBpbGVyLiAqL1xuLy8gdHNsaW50OmRpc2FibGUtbmV4dC1saW5lOm5vLXZhci1yZXF1aXJlc1xuZXhwb3J0IGNvbnN0IFZFUlNJT04gPSBgJHtyZXF1aXJlKCcuLi9wYWNrYWdlLmpzb24nKS52ZXJzaW9uLnJlcGxhY2UoL1xcK1swLTlhLWZdKyQvLCAnJyl9IChidWlsZCA4Yjc2ODJjKWA7XG4iXX0=

package.json

 {
   "name": "jsii",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "TypeScript compiler for jsii",
@@ -12,3 +12,3 @@ "main": "lib/index.js",
     "watch": "tsc -w",
-    "build": "/bin/bash generate.sh && tsc && chmod +x bin/jsii",
+    "build": "cp ../../README.md . && /bin/bash generate.sh && tsc && chmod +x bin/jsii",
     "test": "nodeunit test/test.*.js",
@@ -29,3 +29,3 @@ "package": "package-js"
     "@types/yargs": "^11.0.0",
-    "jsii-build-tools": "^0.7.0",
+    "jsii-build-tools": "^0.7.1",
     "nodeunit": "^0.11.2"
@@ -39,3 +39,3 @@ },
     "glob": "^7.1.2",
-    "jsii-spec": "^0.7.0",
+    "jsii-spec": "^0.7.1",
     "sort-json": "^2.0.0",
@@ -42,0 +42,0 @@ "source-map-loader": "^0.2.3",

README.md

@@ -1,1 +0,409 @@
-../../README.md
+# jsii
+
+![Build Status](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiOThRRFVsVlRBTEhocVZOckE0bFlFWEtwNU0xUmtNUlRRclY0R2VYTGJaOXRlaVdaVnREV2lhVGtDUzQzUDRMMCtuYWpSTWo4N1FGTEV5Zm9yZ0dEb2dBPSIsIml2UGFyYW1ldGVyU3BlYyI6InFVbktYSlpDem1YN1JCeU8iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master)
+
+__jsii__ allows code in any language to naturally interact with JavaScript classes.
+
+For example, consider the following TypeScript class:
+
+```ts
+export class HelloJsii {
+    public sayHello(name: string) {
+        return `Hello, ${name}!`
+    }
+}
+```
+
+By compiling our source module using __jsii__, we can now package it as modules
+in one of the supported target languages. Each target module has the exact same
+API as the source. This allows users of that target language to use `HelloJsii`
+like any other class.
+
+> NOTE: Due to performance of the hosted JavaScript engine and marshaling costs,
+__jsii__ modules are likely to be used for development and build tools, as
+oppose to performance-sensitive runtime behavior.
+
+From Java:
+
+```java
+HelloJsii hello = new HelloJsii();
+hello.sayHello("World"); // => Hello, World!
+```
+
+From .NET:
+
+```csharp
+var hello = new HelloJsii();
+hello.SayHello("World"); // => Hello, World!
+```
+
+From Python (WIP):
+
+```python
+hello = HelloJsii()
+hello.say_hello("World"); # => Hello, World!
+```
+
+From Ruby (WIP):
+
+```ruby
+hello = HelloJsii.new
+hello.say_hello 'World' # => Hello, World!
+```
+
+[Here's](#what-kind-of-sorcery-is-this) how it works.
+
+## Getting Started
+
+Let's create our first jsii TypeScript module!
+
+```console
+$ npm init -y
+$ npm i --save-dev jsii jsii-pacmak
+```
+
+Edit your `package.json`:
+
+```js
+{
+  // ...
+  
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "jsii",
+    "watch": "jsii -w",
+    "package": "jsii-pacmak -v"
+  },
+  "jsii": {
+    "outdir": "dist",
+    "targets": {
+      "java": {
+        "package": "com.acme.hello",
+        "maven": {
+          "groupId": "com.acme.hello",
+          "artifactId": "hello-jsii"
+        }
+      },
+      "dotnet": {
+        "namespace": "Acme.HelloNamespace",
+        "packageId": "Acme.HelloPackage"
+      },
+      "sphinx": { }
+    }
+  }
+}
+```
+
+So, what's going on here?
+
+* The `jsii` section in your `package.json` is the [jsii configuration](#configuration) for your module. 
+  It tells jsii which target languages to package, and includes additional required information for the
+  jsii packager.
+* `npm run build` uses `jsii` to compile your code. It invokes the TypeScript compiler (`tsc`) and will compile 
+  your .ts files into .js files.
+* `npm run watch` will invoke `tsc -w` which will monitor your filesystem for changes and recompile 
+   your .ts files to .js (note that jsii errors will not be reported in this mode)
+* `npm run package` invokes `jsii-pacmak`, which is the __jsii packager__. It will generate _and compile_ your 
+   package to all target languages. The output packages will be emitted to `outdir` (in the above case `dist`).
+* Other required `package.json` fields: `license`, `main`, `types`.
+
+Okay, we are ready to write some code. Create a `lib/index.ts` file:
+
+```ts
+export class HelloJsii {
+  public sayHello(name: string) {
+    return `Hello, ${name}!`;
+  }
+}
+```
+
+Build your module:
+
+```console
+$ npm run build
+```
+
+If build succeeds, you will see the resulting .js file (`lib/index.js`) produced by the
+TypeScript compiler.
+
+You should also see a `.jsii` file in the root:
+
+```json
+{
+  "fingerprint": "HB39Oy4HWtsnwdRnAFYl+qlmy8Z2tmaGM2KDDe9/hHo=",
+  "license": "Apache-2.0",
+  "name": "hello-jsii",
+  "schema": "jsii/1.0",
+  "targets": {
+    "dotnet": {
+      "namespace": "Acme.HelloNamespace",
+      "packageId": "Acme.HelloPackage"
+    },
+    "java": {
+      "maven": {
+        "artifactId": "hello-jsii",
+        "groupId": "com.acme.hello"
+      },
+      "package": "com.acme.hello"
+    },
+    "js": {
+      "npm": "hello-jsii"
+    }
+  },
+  "types": {
+    "hello-jsii.HelloJsii": {
+      "assembly": "hello-jsii",
+      "fqn": "hello-jsii.HelloJsii",
+      "initializer": {
+        "initializer": true
+      },
+      "kind": "class",
+      "methods": [
+        {
+          "name": "sayHello",
+          "parameters": [
+            {
+              "name": "name",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "name": "HelloJsii",
+      "namespace": "hello-jsii"
+    }
+  },
+  "version": "1.0.0"
+}
+```
+
+This file includes all the information needed in order to package your module into every
+jsii-supported language. It contains the module metadata from `package.json` and a full declaration
+of your module's public API.
+
+Okay, now the magic happens:
+
+```console
+$ npm run package
+[jsii-pacmak] [INFO] Building hello-jsii (java,dotnet,sphinx,npm) into dist
+```
+
+Now, if you check out the contents of `dist`, you'll find:
+
+```
+├── dotnet
+│   └── Acme.Hello.nupkg
+├── java
+│   └── com
+│       └── acme
+│           └── hello
+│               └── hello-jsii
+│                   ├── 1.0.0
+│                   │   ├── hello-jsii-1.0.0-javadoc.jar
+│                   │   ├── hello-jsii-1.0.0-javadoc.jar.md5
+│                   │   ├── hello-jsii-1.0.0-javadoc.jar.sha1
+│                   │   ├── hello-jsii-1.0.0-sources.jar
+│                   │   ├── hello-jsii-1.0.0-sources.jar.md5
+│                   │   ├── hello-jsii-1.0.0-sources.jar.sha1
+│                   │   ├── hello-jsii-1.0.0.jar
+│                   │   ├── hello-jsii-1.0.0.jar.md5
+│                   │   ├── hello-jsii-1.0.0.jar.sha1
+│                   │   ├── hello-jsii-1.0.0.pom
+│                   │   ├── hello-jsii-1.0.0.pom.md5
+│                   │   └── hello-jsii-1.0.0.pom.sha1
+│                   ├── maven-metadata.xml
+│                   ├── maven-metadata.xml.md5
+│                   └── maven-metadata.xml.sha1
+├── js
+│   └── [e-mail]
+└── sphinx
+    └── hello-jsii.rst
+```
+
+These files are ready-to-publish artifacts for each target language. You can
+see the npm tarball under `js`, the Maven repo under `java`, the Sphinx .rst file
+under `sphinx`, etc.
+
+That's it. You are ready to rock!
+
+## Configuration
+
+jsii configuration is read from the module's `package.json` and includes the following options:
+
+ * `targets` - the list of target languages this module will be packaged for. For each
+   target, you would need to specify some naming information such as namespaces, package manager
+   coordinates, etc. See [supported targets](#targets) for details.
+ * `outdir` - the default output directory (relative to package root) for
+   __jsii-pacmak__. This is where target artifacts are emitted during packaging. Each artifact
+   will be emitted under `<outdir>/<target>` (e.g. `dist/java`, `dist/js`, etc).
+
+### Targets
+
+The following targets are currently supported:
+
+ * `js` - implicit - every module will always have a "js" target (dah!).
+ * `java` - packages the module as in Java/Maven package. Requires the following config:
+
+```json
+{
+  "java": {
+    "package": "com.acme.hello",
+    "maven": {
+      "groupId": "com.acme.hello",
+      "artifactId": "hello-jsii"
+    }
+  }
+}
+```
+
+* `dotnet` - packages the module as a .NET/NuGet package. Requires the following config:
+
+```js
+{
+  "dotnet": {
+    /* Required. */
+    "namespace": "Acme.HelloNamespace",
+
+    /* Required. */
+    "packageId": "Acme.HelloPackage",
+
+    /* Optional. Default: Value of packageId. */
+    "title": "ACME Hello",
+
+    /* Optional. Default: null (no icon). */
+    "iconUrl": "path/to/icon.svg",
+
+    /* Optional. Used in conjunction with assemblyOriginatorKey. Default: false. */
+    "signAssembly": true,
+
+    /* Optional. Used in conjunction with signAssembly. Default: null. */
+    "assemblyOriginatorKey": "path/to/key.snk"
+  }
+}
+```
+
+* `sphinx` - produces sphinx documentation for the module. No config is required, but an empty
+  entry will be needed in order to package this target:
+
+```json
+{
+  "sphinx": { }
+}
+```
+
+
+## Features
+
+### Language features
+
+ * Classes
+ * Inheritance
+ * Constructors
+ * Methods
+ * Properties
+ * Abstract Members
+ * Virtual Overrides
+ * Async Methods
+ * Variadic Arguments
+ * Static Methods and Properties
+ * Static Constants
+ * Abstract Classes
+ * Interfaces
+ * Enums
+ * Primitive Types: string, number, boolean, date, json, any
+ * Collection Types: arrays, maps
+ * Union Types (limited support)
+ * Module Dependencies
+ * Data Interfaces
+
+### Source Languages
+
+ * TypeScript
+
+### Target Languages
+
+ * __Java__ - generates a ready-to-publish Maven package.
+ * __.NET__ - generates a ready-to-publish NuGet package.
+ * __Sphinx__ - generates a Sphinx reStructuredText document for the module with README and reference docs.
+ * __Python__ (work in progress) - generates a ready-to-publish PyPI package.
+ * __Ruby__ (work in progress) - generates a ready-to-publish RubyGem.
+
+## What kind of sorcery is this?
+
+So how does this thing work?
+
+Given a source npm module written in one of the supported _source_ languages
+(currently, only [TypeScript] is supported as source), we produce a "header
+file" (called the ".jsii spec") which describes the public API for the module.
+
+[TypeScript]: https://www.typescriptlang.org/
+
+Here the .jsii spec for the above example:
+
+```json
+{
+  "types": {
+    "hello-jsii.HelloJsii": {
+      "assembly": "hello-jsii",
+      "fqn": "hello-jsii.HelloJsii",
+      "initializer": {
+        "initializer": true
+      },
+      "kind": "class",
+      "methods": [
+        {
+          "name": "sayHello",
+          "parameters": [
+            {
+              "name": "name",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "name": "HelloJsii",
+      "namespace": "hello-jsii"
+    }
+  }
+}
+```
+
+Now, we have two artifacts: the compiled module with .js code and the .jsii spec.
+This two artifacts are used as input to the next stage we call __pacmak__
+(stands for "package maker").
+
+__pacmak__ reads the .jsii spec and module information from `package.json` and
+generates a _ready-to-publish_ package artifact for each requested target
+language. For example, it will produce a Maven package for Java, a NuGet package
+for .NET, a PyPI module for Python, etc.
+
+The generated packages include _proxy classes_ which represent the API of source
+module, "translated" to the idioms and conventions of each target language. So
+if we had a `HelloJsii` class in the source module with a method `sayHello`, the
+.NET generator will emit a `HelloJsii` class with a method `SayHello`.
+
+At runtime, when code interacts with proxy classes - creates instances, invokes
+methods, gets or sets properties - the calls are marshaled in and out to a
+Node.js VM loaded with the source JavaScript module.
+
+# Contributing
+
+See [CONTRIBUTING](./CONTRIBUTING.md).
+
+## License
+
+__jsii__ is distributed under the
+[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for more information.

No alert changes

Improved metrics

Total package byte prevSize

503784

increased by2.88%

Number of package files

117

increased by1.74%

Lines of code

3376

increased by0.66%

Number of lines in readme file

410

increased by40900%

Dependency changes

• Updatedjsii-spec@^0.7.1