Merge pull request #8 from 43081j/typescript

1.0.0

Author: 43081j

.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*]
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = true

.gitignore

@@ -1,2 +1,3 @@
 *.swp
-build/
+lib/
+node_modules/

.npmignore

@@ -0,0 +1,7 @@
+node_modules
+tslint.json
+src/
+lib/test/
+test/
+.travis.yml
+.editorconfig

.travis.yml

@@ -0,0 +1,6 @@
+language: node_js
+node_js:
+  - "8"
+  - "node"
+script:
+- npm test

README.md

@@ -1,82 +1,67 @@
-rar.js - JavaScript Unrar Utility
-===
+# rar.js - JavaScript Unrar Utility
 
 **rar.js** provides a pure javascript implementation of the rar format, allowing you to extract or manipulate packed data client-side and server-side.
 
 Multiple inputs are supported: AJAX, File API (HTML5) and local disk (NodeJS).
 
-**rar.js** makes use of [dataview-extra](https://github.com/43081j/dataview-extra) and [reader.js](https://github.com/43081j/reader.js).
+## Example
 
-**This is a very new utility/library, please see the list below for what may be missing.**
+Using **rar.js** is fairly straight forward.
+
+```javascript
+Rar.fromLocal('myfile.rar').then((archive) => {
+  // Use archive here
+  console.log(archive.entries);
+});
 
-**TODO & Potential Features**
+Rar.fromUri('/test.rar').then((archive) => {
+  // Use archive here
+});
+
+Rar.fromFile(input.files[0]).then((archive) => {
+  // Use archive here
+});
+```
+
+## Unsupported features (TODO)
 
 * Large file support (currently the entire file will be in memory when `RarArchive.get` is called)
 * Decompression support
 * Encryption support
 * Recognise volumes/split archives
 * Parse other entries (e.g. comments)
 
-Example
-===
+## Saving files
 
-Using **rar.js** is fairly straight forward.
+By using `RarArchive#get(file)`, you can retrieve a `Blob` of a specified file within the archive.
 
 ```javascript
-var archive = RarArchive(file, function(err) {
-	if(err) {
-		// An error occurred (not a rar, read error, etc)
-		return;
-	}
-	// Use archive
-});
+const file = archive.get(archive.entries[0]);
+const url = URL.createObjectURL(file);
+// Do something with url here
+// like creating an <a> tag with the download attribute set
 ```
 
-In this example, the callback is called when the archive has been opened and validated successfully. If the archive is of an invalid format or cannot be read, an appropriate error will be passed.
-
-Within the callback, `archive.entries` has been populated with the files (note you may use `this.entries` in the callback too).
-
-Each entry is a `RarEntry` instance.
-
-Saving files
-===
-
-By using `RarArchive.get(file, callback)`, you can retrieve a `Blob` of a specified file within the archive.
-
-What you do with this `Blob` is upto you. A common thing to do would be to create an object URL using `URL.createObjectURL(Blob)` and redirect the user to it or create an `<a>` element with the `download` attribute (HTML5) set to the file name.
-
-Split Volumes
-===
+### Split Volumes
 
 When dealing with entries you have retrieved via `RarArchive.get()`, make sure you check the `RarEntry.partial` boolean.
 
 If this boolean is true, sending/saving the `Blob` will result in a partial file. You must request that the user open the previous or next volume and prepend/append to the `Blob` to be able to retrieve the full file.
 
 To find out if the file is continued in a previous or next volume, see `RarEntry.continues` and `RarEntry.continuesFrom`.
 
-RarArchive
-===
+## RarArchive
 
-* `RarArchive(options, callback)` If options is a string, it is assumed to be a URL. If it is a File instance, it will be treated as such. `callback` will be called when the archive has been validated and is ready.
-* `RarArchive.entries` An array of `RarEntry` instances contained within this archive
-* `RarArchive.get(RarEntry, callback)` Retrieves the specified `RarEntry` and passed a `Blob` of it to `callback`
-
-When creating an instance of `RarArchive`, the data source is guessed based on data type. If it is a string, it is assumed to be a URL and will be requested over HTTP. If it is a `File` instance, it will be read as one.
-
-In the case that you want to specify the type manually or want to read a local file, you must pass it in the options like so:
-
-```
-RarArchive({ type: RarArchive.OPEN_LOCAL, file: 'example/file.txt'}, function() { });
-```
+* `Rar.fromFile(file)` where `file` is a HTML5 `File` instance
+* `Rar.fromLocal(path)` where `path` is a string of a local filesystem path
+* `Rar.fromUri(uri)` where `uri` is a string of a URI
 
-You may use the following constants for `type`:
+All three of these entrypoints return a `Promise` which resolves to a `RarArchive`.
 
-* `RarArchive.OPEN_LOCAL` for local files (NodeJS only)
-* `RarArchive.OPEN_URI` for HTTP URIs
-* `RarArchive.OPEN_FILE` for File instances
+* `RarArchive#entries` An array of `RarEntry` instances contained within this archive
+* `RarArchive#get(RarEntry)` Retrieves the specified `RarEntry` resolves a promise with a `Blob`
 
-RarEntry Properties
-===
+## RarEntry Properties
 
 * `name` File name
 * `path` File path within the archive, including file name
@@ -97,14 +82,13 @@ RarEntry Properties
 
 The following constants also exist for use with `RarEntry.method`:
 
-* `RarEntry.METHOD_STORE`
-* `RarEntry.METHOD_FASTEST`
-* `RarEntry.METHOD_FAST`
-* `RarEntry.METHOD_NORMAL`
-* `RarEntry.METHOD_GOOD`
-* `RarEntry.METHOD_BEST`
+* `Rar.RarMethod.STORE`
+* `Rar.RarMethod.FASTEST`
+* `Rar.RarMethod.FAST`
+* `Rar.RarMethod.NORMAL`
+* `Rar.RarMethod.GOOD`
+* `Rar.RarMethod.BEST`
 
-License
-===
+## License
 
 MIT

examples/index.html

@@ -1,32 +1,28 @@
 <!DOCTYPE html>
 <html>
-	<head>
-		<title>Test</title>
-	</head>
-	<body>
-		<!-- Make a file input for you to select an archive -->
-		<input type="file">
-		<br>
-		<!-- Include rar.js -->
-		<script src="../dist/rar.js"></script>
-		<script type="text/javascript">
-			document.querySelector('input[type="file"]').onchange = function(e) {
-				/*
-				   Pass the File instance to rar.js
-				   You could iterate over this.files to handle many at once
-				*/
-				var file = RarArchive(this.files[0], function(err) {
-					if(err) {
-						console.log(err);
-						return;
-					}
-					this.entries.forEach(function(val) {
-						var div = document.createElement('div');
-						div.textContent = val.path;
-						document.body.appendChild(div);
-					});
-				});
-			}
-		</script>
-	</body>
+  <head>
+    <title>Test</title>
+  </head>
+  <body>
+    <!-- Make a file input for you to select an archive -->
+    <input type="file">
+    <br>
+    <!-- Include rar.js -->
+    <script src="../rar.js"></script>
+    <script type="text/javascript">
+      document.querySelector('input[type="file"]').onchange = function(e) {
+        /*
+           Pass the File instance to rar.js
+           You could iterate over this.files to handle many at once
+        */
+        var file = Rar.fromFile(this.files[0]).then((archive) => {
+          archive.entries.forEach(function(val) {
+            var div = document.createElement('div');
+            div.textContent = val.path;
+            document.body.appendChild(div);
+          });
+        });
+      }
+    </script>
+  </body>
 </html>

examples/test.js

@@ -1,7 +1,7 @@
-var RarArchive = require('rarjs');
+var Rar = require('rarjs');
 
-var file = RarArchive({type: RarArchive.OPEN_LOCAL, file: '../build/test.rar'}, function(err) {
-	this.entries.forEach(function(val) {
+Rar.fromLocal('test.rar').then((archive) => {
+	archive.entries.forEach((val) => {
 		console.log(val.path);
 	});
 });