@azure-iot/hal - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

package.json

 {
   "name": "@azure-iot/hal",
   "description": "Decorator library for HAL-based routes",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "scripts": {
@@ -6,0 +6,0 @@ "prebuild": "npm run lint",

README.md

@@ -21,3 +21,3 @@ # @azure-iot/hal
 * `options` [provides.Options.Namespace] *(optional)*:
-    * `href` [string]: The documentation link representing this namespace; this contains the placeholder 'rel' for the rels provided by the routes of this server, as per the HAL spec. It can accept either URI-template or Express syntax, as per the `@route` decorator. Default is '/docs/<namespace>/:rel'.
+    * `href` [string | Url]: The documentation link representing this namespace; this contains the placeholder 'rel' for the rels provided by the routes of this server, as per the HAL spec. It can accept either URI-template or Express syntax, as per the `@route` decorator. Default is '/docs/<namespace>/:rel'.
     * `auto` [boolean]: Indicates whether to automatically generate documentation from the `description` attributes, described below; default is false if `href` is specified, true otherwise.
@@ -38,3 +38,3 @@ * `template` [string]: A [Mustache](https://mustache.github.io/) template used to format the automatically-generated documentation. The format of the provided object is the `Template` type, specified below.
 * `method` [string | Method]: The HTTP method from the `Method` enum or as a string.
-* `path` [string]: The route path for this handler. Express-style paths and level-1 URI templated paths (as per [RFC 6570](https://tools.ietf.org/html/rfc6570)) are supported.
+* `path` [string | Url]: The route path for this handler. Express-style paths and level-1 URI templated paths (as per [RFC 6570](https://tools.ietf.org/html/rfc6570)) are supported.
 
@@ -77,3 +77,3 @@ #### `@provides(rel, [options])`
         * `rel` [string | LinkRelation]: The HAL response will include the link under this rel, though the href will still be populated automatically as normal.
-        * `href` [string]: The HAL response will use the provided href for this rel, rather than the server-provided one.
+        * `href` [string | Url]: The HAL response will use the provided href for this rel, rather than the server-provided one. If a Url object is provided, it will be merged with the server-provided href before being resolved.
         * `server` [Object]: The server class used for non-namespaced and standard rels.
@@ -91,3 +91,3 @@ * `links` [Array<string | LinkRelation>]: The array of rels associated with this link. This corresponds to the array of rels provided to the `@hal` decorator for this link, plus the 'self' rel if it would typically be present, and is used for link embedding when necessary.
     * `ns` [string]: The namespace of this documentation.
-    * `href` [string]: The documentation link representing this namespace; as per HAL.
+    * `href` [string | Url]: The documentation link representing this namespace; as per HAL.
 
@@ -94,0 +94,0 @@ ### Functions

src/api.d.ts

 import * as express from 'express';
 import { provides, middleware, filter, hal } from './decorators';
-import { Verb, Rel } from './constants';
+import { Verb, Rel, Href } from './constants';
 export declare namespace Api {
@@ -19,3 +19,3 @@ class Api {
         hal(...args: (Rel | hal.Options)[]): this;
-        route(verb: Verb, path: string): this;
+        route(verb: Verb, path: Href): this;
         middleware(handler: express.RequestHandler): this;
@@ -22,0 +22,0 @@ filter(filter: filter.Filter): this;

src/arguments.d.ts

 import * as express from 'express';
-import { Rel, Verb } from './constants';
+import { Rel, Verb, Href } from './constants';
 import { provides, middleware, filter, hal } from './decorators';
@@ -29,3 +29,3 @@ export declare namespace Arguments {
             verb: Verb;
-            path: string;
+            path: Href;
         }
@@ -32,0 +32,0 @@ interface Provides {

src/constants.d.ts

@@ -0,1 +1,2 @@
+import * as url from 'url';
 import { provides } from './decorators';
@@ -98,2 +99,6 @@ export declare enum Method {
 }
+export declare type Href = string | url.Url;
+export declare namespace Href {
+    function stringify(href: Href): string;
+}
 export declare namespace Hal {
@@ -100,0 +105,0 @@ interface Link {

src/constants.js

 "use strict";
+const url = require('url');
 (function (Method) {
@@ -107,2 +108,9 @@ Method[Method["GET"] = 1] = "GET";
 })(Rel = exports.Rel || (exports.Rel = {}));
+var Href;
+(function (Href) {
+    function stringify(href) {
+        return typeof href === 'string' ? href : url.format(href);
+    }
+    Href.stringify = stringify;
+})(Href = exports.Href || (exports.Href = {}));
 //# sourceMappingURL=constants.js.map

src/decorators.d.ts

 import * as express from 'express';
-import { Verb, Rel, Template } from './constants';
+import { Verb, Rel, Template, Href } from './constants';
 import { Api } from './api';
@@ -12,3 +12,3 @@ export declare function provides(rel?: Rel, options?: provides.Options.Namespace & provides.Options.Rel): ClassDecorator & MethodDecorator;
         interface Namespace {
-            href?: string;
+            href?: Href;
             auto?: boolean;
@@ -33,3 +33,3 @@ template?: string;
         rel?: Rel;
-        href?: string;
+        href?: Href;
         server?: Object;
@@ -41,3 +41,3 @@ links?: Rel[];
         embed(rel: Rel, value: Object, overrides?: Overrides): Response;
-        docs(name: string, href: string): void;
+        docs(name: string, href: Href): void;
     }
@@ -47,3 +47,3 @@ const discovery: express.RequestHandler;
 export declare function route(target: Object): express.Application;
-export declare function route(verb: Verb, path: string): MethodDecorator;
+export declare function route(verb: Verb, path: Href): MethodDecorator;
 export declare function middleware(handler: express.RequestHandler | express.ErrorHandler, options?: middleware.Options): ClassDecorator & MethodDecorator;
@@ -50,0 +50,0 @@ export declare namespace middleware {

src/response.d.ts

 import * as express from 'express';
 import * as halson from 'halson';
-import { Rel, Hal } from './constants';
+import { Rel, Hal, Href } from './constants';
 import { hal } from './decorators';
@@ -14,3 +14,3 @@ export declare class Response implements hal.Response {
     embed(rel: Rel, value: Object, overrides?: hal.Overrides): hal.Response;
-    docs(name: string, href: string): void;
+    docs(name: string, href: Href): void;
 }
@@ -17,0 +17,0 @@ export declare namespace Response {

src/response.js

 "use strict";
 const halson = require('halson');
+const url = require('url');
 const server_1 = require('./server');
@@ -67,2 +68,5 @@ const template_1 = require('./template');
             let resolved = Object.assign({}, base, link, overrides);
+            if (overrides.href && typeof overrides.href === 'object') {
+                resolved.href = Object.assign(url.parse(link.href), overrides.href);
+            }
             if (!overrides.params) {
@@ -114,7 +118,3 @@ resolved.params = Object.assign({}, base.params, link.params);
             delete params[constants_1.Rel.Param];
-            _private(_private(this).root).hal.addLink(constants_1.Rel.Curies, template_1.Template.link({
-                href: href,
-                id: name,
-                params
-            }));
+            _private(_private(this).root).hal.addLink(constants_1.Rel.Curies, template_1.Template.link({ href, id: name, params }));
         }
@@ -121,0 +121,0 @@ }

src/server.js

@@ -78,8 +78,6 @@ "use strict";
         for (let provides of handler.args.provides) {
-            let template = template_1.Template.apply(route.path, provides.options.params || {});
-            Server.linker.registerLink(server, provides.rel, template, Object.assign({
-                verb: route.verb,
-                href: route.path,
-                links
-            }, provides.options));
+            let verb = route.verb;
+            let href = constants_1.Href.stringify(route.path);
+            let template = template_1.Template.apply(href, provides.options.params || {});
+            Server.linker.registerLink(server, provides.rel, template, Object.assign({ verb, href, links }, provides.options));
         }
@@ -117,3 +115,3 @@ let handlers = middleware.map(cb => (req, res, next) => Promise.resolve(cb(req, res, next)).catch(next));
             for (let provides of proto.provides) {
-                const href = provides.options.href || `/docs/${provides.namespace}/:${constants_1.Rel.Param}`;
+                const href = constants_1.Href.stringify(provides.options.href || '') || `/docs/${provides.namespace}/:${constants_1.Rel.Param}`;
                 Server.linker.registerDocs(server, provides.namespace, href);
@@ -120,0 +118,0 @@ if ((typeof provides.options.auto === 'undefined' && typeof provides.options.href === 'undefined') || provides.options.auto) {

src/template.js

@@ -31,5 +31,9 @@ "use strict";
     static link(resolved) {
-        let link = { href: resolved.href };
-        if (resolved.href && resolved.params) {
-            link.href = Template.apply(resolved.href, resolved.params);
+        let link = {
+            href: typeof resolved.href === 'string' ?
+                resolved.href :
+                Template.decode(url.format(resolved.href || {}))
+        };
+        if (resolved.params) {
+            link.href = Template.apply(link.href, resolved.params);
         }
@@ -36,0 +40,0 @@ if (Template.l4.test(link.href)) {

No alert changes

Improved metrics

Total package byte prevSize

62410

increased by1.33%

Lines of code

1087

increased by1.4%

No dependency changes