@balena/sbvr-types - npm Package Compare versions

Comparing version 3.5.0-build-web-resource-2-5970f795b22d100340b0644f68e0ff49208bf955-1 to 3.5.0-build-web-resource-2-848c8563bf52fe6873d2242da10a489852f83e69-1

CHANGELOG.md

@@ -8,6 +8,11 @@ # Change Log
 # v3.5.0
-## (2022-11-29)
+## (2022-12-13)
 
 * Add type WebResource [Ramiro González Maciel]
 
+# v3.4.19
+## (2022-12-08)
+
+* Flowzone: Allow external contributions [Josh Bowling]
+
 # v3.4.18
@@ -14,0 +19,0 @@ ## (2022-11-25)

out/storage-adapters/index.d.ts

@@ -1,3 +0,5 @@
-import { StorageRegistry } from './storage-adapter';
-export * from './storage-adapter';
-export declare const storageRegistry: StorageRegistry;
+import { StorageAdapter } from './types';
+export * from './types';
+export declare function registerStorageAdapter(name: string, adapter: StorageAdapter): void;
+export declare function getStorageAdapter(name: string): StorageAdapter;
+export declare function unregisterStorageAdapter(name: string): void;

out/storage-adapters/index.js

@@ -17,5 +17,17 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.storageRegistry = void 0;
-__exportStar(require("./storage-adapter"), exports);
-exports.storageRegistry = {};
+exports.unregisterStorageAdapter = exports.getStorageAdapter = exports.registerStorageAdapter = void 0;
+__exportStar(require("./types"), exports);
+const storageRegistry = {};
+function registerStorageAdapter(name, adapter) {
+    storageRegistry[name] = adapter;
+}
+exports.registerStorageAdapter = registerStorageAdapter;
+function getStorageAdapter(name) {
+    return storageRegistry[name];
+}
+exports.getStorageAdapter = getStorageAdapter;
+function unregisterStorageAdapter(name) {
+    delete storageRegistry[name];
+}
+exports.unregisterStorageAdapter = unregisterStorageAdapter;
 //# sourceMappingURL=index.js.map

out/types/web-resource.js

@@ -28,3 +28,8 @@ "use strict";
     if (typeof data === 'string') {
-        refData = JSON.parse(data);
+        try {
+            refData = JSON.parse(data);
+        }
+        catch (e) {
+            throw new Error(`can't be parsed from stored value ${typeof data} with error ${e.message}`);
+        }
     }
@@ -35,3 +40,3 @@ else if (typeof data === 'object') {
     else {
-        throw new Error('Unable to parse data for a WebResource type. Data is: ' + data);
+        throw new Error(`can't be read from stored value ${typeof data}`);
     }
@@ -49,3 +54,3 @@ return {
     if (typeof value !== 'object') {
-        throw new Error('received value is not an object');
+        throw new Error(`is not an object: ${typeof value}`);
     }
@@ -62,5 +67,5 @@ if (!value.filename) {
     }
-    const storageAdapter = index_1.storageRegistry[storage];
+    const storageAdapter = (0, index_1.getStorageAdapter)(storage);
     if (!storageAdapter) {
-        throw new Error(`storage ${storage} not defined. Available adapters: ${Object.keys(index_1.storageRegistry)}`);
+        throw new Error(`storage ${storage} not defined`);
     }
@@ -75,5 +80,10 @@ const webresource = await storageAdapter.saveFile(value.filename, value.data);
     };
-    const processedValue = JSON.stringify(refData);
-    return processedValue;
+    try {
+        const processedValue = JSON.stringify(refData);
+        return processedValue;
+    }
+    catch (e) {
+        throw new Error(`can't be stringified with error ${e.message}`);
+    }
 });
 //# sourceMappingURL=web-resource.js.map

package.json

 {
   "name": "@balena/sbvr-types",
-  "version": "3.5.0-build-web-resource-2-5970f795b22d100340b0644f68e0ff49208bf955-1",
+  "version": "3.5.0-build-web-resource-2-848c8563bf52fe6873d2242da10a489852f83e69-1",
   "description": "SBVR type definitions.",
@@ -55,4 +55,4 @@ "main": "out",
   "versionist": {
-    "publishedAt": "2022-11-29T16:47:29.450Z"
+    "publishedAt": "2022-12-13T13:37:24.183Z"
   }
 }

README.md

@@ -1,7 +0,4 @@
-## sbvr-types
+# sbvr-types
 
-This module defines the data types that can be used in the SBVR model
-specification, as well as the possible relations between them. For each data 
-type, there is a correspondence with a database data type, according to the 
-various database engines that are supported.
+This module defines the data types that can be used in the SBVR model specification, as well as the possible relations between them. For each data type, there is a correspondence with a database data type, according to the various database engines that are supported.
 
@@ -12,7 +9,8 @@ The SBVR definition for types can be found at [Type.sbvr](https://github.com/balena-io-modules/sbvr-types/blob/master/Type.sbvr)
 
-### How-to
+## How-to
 
 For a new type you should add a module to the types folder. The module should return a single object, which has the following format:
 
-#### types
+### types
+
 A types object, which specifies how the type is declared in various systems. This contains:
@@ -155,5 +153,36 @@
 
+## Tests
 
-### Tests
+Tests can be found under the `test/` folder, to run the whole suite use `npm test`
 
-Tests can be found under the `test/` folder, to run the whole suite use `npm test`
+## Storing files and other large objects
+
+An application can choose between two types to save file content or another large object: `File` or `WebResource`. When using a `File`, PineJS saves the content in the database using a binary data type like `BYTEA` or `BLOB`. When using a `WebResource`, PineJS saves the binary content on an external storage service and then writes metadata, including the content public URL, to the database. Client apps use the `WebResource` `href` to get the content.
+
+
+### WebResource
+
+Type [`WebResource`](./src//types/web-resource.ts) can be used to persist files or other large content on an external object storage service like Amazon S3. By "object storage" we refer to a service that can store the content and provide a URL to access that content.
+
+In order to save a `WebResource` you send an instance of [`WebResourceInput`](./src/types/web-resource.ts#L18)
+
+```js
+{
+  filename: string;
+  data: Buffer;
+  contentType?: string;
+  contentDisposition?: string;
+  size?: number;
+  storage: string;
+}
+```
+
+A typical use case is to have a web app where users can upload a file. The app will use [multer](https://github.com/expressjs/multer) to get the file from the http request as a `Buffer` and pass it as the `data` attribute of a `WebResourceInput`.
+
+When retrieving a `WebResource` the `data` attribute is replaced by an `href`( URL ) attribute. See [`WebResourceRef`](./src/types/web-resource.ts#L7)
+
+#### Storage Adapters
+
+The `storage` attribute specifies the name of an [`StorageAdapter`](./src/storage-adapters/storage-adapter.ts#L7). A `StorageAdapter` saves the content to a specific storage, performing a function similar to what a database driver provides. For example, [pinejs-s3-storage](https://github.com/balena-io-modules/pinejs-s3-storage) saves the content to S3 and returns a URL to the persisted object. For testing purposes, this module uses [disk-storage-adapter](./test/storage-adapters/disk-storage-adapter.js).
+
+Applications need to load the `StorageAdapter`s they need in the `storageRegistry`(./src/storage-adapters/index.ts#L4). Please refer to each specific storage adapter for more configuration and setup details.

src/storage-adapters/index.ts

@@ -1,4 +0,19 @@
-import { StorageRegistry } from './storage-adapter';
+import { StorageAdapter, StorageRegistry } from './types';
 
-export * from './storage-adapter';
-export const storageRegistry: StorageRegistry = {};
+export * from './types';
+const storageRegistry: StorageRegistry = {};
+
+export function registerStorageAdapter(
+	name: string,
+	adapter: StorageAdapter,
+): void {
+	storageRegistry[name] = adapter;
+}
+
+export function getStorageAdapter(name: string): StorageAdapter {
+	return storageRegistry[name];
+}
+
+export function unregisterStorageAdapter(name: string): void {
+	delete storageRegistry[name];
+}

src/types/web-resource.ts

 import * as TypeUtils from '../type-utils';
-import { storageRegistry } from '../storage-adapters/index';
+import { getStorageAdapter } from '../storage-adapters/index';
 
@@ -50,9 +50,15 @@ /**
 	if (typeof data === 'string') {
-		refData = JSON.parse(data);
+		try {
+			refData = JSON.parse(data);
+		} catch (e: any) {
+			throw new Error(
+				`can't be parsed from stored value ${typeof data} with error ${
+					e.message
+				}`,
+			);
+		}
 	} else if (typeof data === 'object') {
 		refData = data;
 	} else {
-		throw new Error(
-			'Unable to parse data for a WebResource type. Data is: ' + data,
-		);
+		throw new Error(`can't be read from stored value ${typeof data}`);
 	}
@@ -72,3 +78,3 @@
 		if (typeof value !== 'object') {
-			throw new Error('received value is not an object');
+			throw new Error(`is not an object: ${typeof value}`);
 		}
@@ -86,9 +92,5 @@ if (!value.filename) {
 		}
-		const storageAdapter = storageRegistry[storage];
+		const storageAdapter = getStorageAdapter(storage);
 		if (!storageAdapter) {
-			throw new Error(
-				`storage ${storage} not defined. Available adapters: ${Object.keys(
-					storageRegistry,
-				)}`,
-			);
+			throw new Error(`storage ${storage} not defined`);
 		}
@@ -108,5 +110,9 @@
 		};
-		const processedValue = JSON.stringify(refData);
-		return processedValue;
+		try {
+			const processedValue = JSON.stringify(refData);
+			return processedValue;
+		} catch (e: any) {
+			throw new Error(`can't be stringified with error ${e.message}`);
+		}
 	},
 );

No alert changes

Improved metrics

Total package byte prevSize

124010

increased by4.18%

Lines of code

1942

increased by2.21%

Number of lines in readme file

187

increased by18.35%

No dependency changes