jsfiledeprecated

JavaScript library for working with files in browser

Usage no npm install needed!

<script type="module">
  import jsfile from 'https://cdn.skypack.dev/jsfile';
</script>

README

JsFile

Build Status npm npm bountysource Coverage Status

JavaScript library for working with files in browser. See demo on https://jsfile.github.io/jsFile/

Installation

via NPM

You can install a jsFile package very easily using NPM. After installing NPM on your machine, simply run:

$ npm install jsfile

with Git

You can clone the whole repository with Git:

$ git clone git://github.com/jsFile/jsFile.git

from latest version

Also you can download the latest release of jsFile and include built files to your project.

Usage

You can include jsFile to your project in different ways:

as independent file from

<script src="path_to_js/dist/jsfile.js"></script>
<script>
    window.JsFile; //use an object in global namespace
</script>

as CommonJS module

var JsFile = require('JsFile');

as ES6 module

import JsFile from 'JsFile';

Include one or more engines for necessary file types. See all list of engines

import JsFile from 'JsFile';
import JsFileDsv from 'jsfile-dsv'; //read .csv
import JsFileOoxml from 'jsfile-ooxml'; //read .docx

JsFile.defineEngine(JsFileDsv);
JsFile.defineEngine(JsFileOoxml);
const jf = new JsFile(file, options);

API

JsFile

JsFile.version

Type: String

It's a current version of library.

JsFile.isSupported

Type: Boolean

It shows that jsFile can work in current browser or not.

JsFile.isSupported;

JsFile.mimeTypes

Type: Array

Contains list of supported mime-type in jsFile engines.

JsFile.mimeTypes; //[...supported mime-types...]

JsFile.defineEngine()

Returns JsFile.Engine object or null (if engine is invalid). You can create your own documents engine for jsFile and include it to the library.

JsFile.defineEngine(Engine);

Engine {Function} - it's an inherited class from JsFile.Engine. It must have static property mimeTypes (array with supported mime types) and static method test to test which type of file is supported.

JsFile.removeEngine(Engine)

Engine {Function} - it's an inherited class from JsFile.Engine. It removes specified Engine from defined engines. If Engine argument isn't defined it removes all defined engines.

JsFile instance

In the next examples I will use JsFile instance:

let jf = new JsFile(file[, options]);

file {File|Blob} [required] (Read about File or Blob)

options {Object} [optional] - object with your custom settings:

jf.read()

Returns Promise object

jf.read().then(
    (document) => {...your success handler...},
    (error) => {...your error handler...}
);

error {Error} - object contains description of the error in error.message property

document - object contains result of file reading. For more details see JsFile.Document

jf.findEngine()

Returns JsFile.Engine or null. This method finds an engine for jf.file.

jf.findEngine()

JsFile.Engine

JsFile.Engine.getCharFromHex(hex)

Returns a character from hex value.

JsFile.Engine.replaceSpaces(str)

Returns String. Replaces 2 and more spaces on \u2000\u2000 value.

JsFile.Engine.test()

Returns Boolean. If you develop a custom JsFile engine, you should override this method:

static test (file) {
    return Boolean(file && Engine.validateFile(file, files));
}

files - Object with meta-information about supported formats:

// Example for FB2 engine:
const files = {
    extension: ['fb2'],
    mime: ['application/x-fictionbook+xml']
};
JsFile.Engine.normalizeDataUri(dataUri, filename)

Normalizes a dataUri string according to specified filename.

const dataUri = 'data:;base64,....';
const filename = 'test.png';
JsFile.Engine.normalizeDataUri(dataUri, filename); //data:image/png;base64,...
JsFile.Engine.formatPropertyName(name, options)
JsFile.Engine.formatPropertyName('namespace:prop'); //property
JsFile.Engine.formatPropertyName('prop-name'); //propName
JsFile.Engine.formatPropertyName('prop-name', {capitalize: true}); //PropName
JsFile.Engine.cropUnit(value)
JsFile.Engine.cropUnit('18px'); //18
JsFile.Engine.normalizeColorValue(value)
JsFile.Engine.normalizeColorValue('black'); //#000000
JsFile.Engine.normalizeColorValue('darkgreen'); //#006400
JsFile.Engine.attributeToBoolean(value)
JsFile.Engine.attributeToBoolean('yes'); //true
JsFile.Engine.attributeToBoolean('on'); //true
JsFile.Engine.attributeToBoolean('off'); //false
JsFile.Engine.normalizeColorValue({value: 1}); //true
JsFile.Engine.validateUrl()

Returns Boolean value. It's utility method for URL validation. Might be helpful in development of custom engines

let engine = new JsFile.defineEngine(...);
engine.validateUrl(url); // true or false

url {String}

JsFile.Engine.merge()

Deep merge of objects;

const a = {
    data: {
        value: 1
    },
         
    name: 'test'
};

const b = {
    data: {
        value: 0
    }
};

JsFile.Engine.merge(a, b);
/*
It returns:
{
    data: {
        value: 0
    },
 
    name: 'test'   
}
*/
JsFile.Engine.clone()

Returns deep clone of object;

JsFile.Engine.errors

{Object}. List of constants with error messages

JsFile.Engine.prototype.isValid

Method of JsFile.Engine instance. Return true if file from engine is supported.

JsFile.Document

JsFile.Document.elementPrototype

Type: Object

It is a static property that contains the base structure for each element of parsed document

{
    "children": [],
    "style": {
        "position": "relative",
        "boxSizing": "border-box"
    },
    "properties": {
        "tagName": "DIV",
        "textContent": ""
    }
}
doc.html()

Returns DocumentFragment with document content presented as HTML

const doc = new JsFile.Document(...);
doc.html();
doc.json()

Returns simple JS Object with parsed document tree

const doc = new JsFile.Document(...);
doc.json(); // {name: '', language: '', content: [...]}
doc.page()

Returns parsed page by index

const doc = new JsFile.Document(...);
doc.page(0);
doc.language

Returns main language of parsed document

const doc = new JsFile.Document(...);
doc.language; // String
doc.name

Returns name of parsed document

const doc = new JsFile.Document(...);
doc.name; // String
doc.wordsCount

Returns number of words in parsed document

const doc = new JsFile.Document(...);
doc.wordsCount; // Number
doc.length

Returns number of pages in parsed document

const doc = new JsFile.Document(...);
doc.length; // Number
doc.zoom

Returns zoom value of parsed document

const doc = new JsFile.Document(...);
doc.zoom; // Number
doc.isEmpty

Type: Boolean

const doc = new JsFile.Document(...);
doc.isEmpty; // Boolean

Tests

  • Clone JsFile sources via Git
  • Install dependencies. Just run the next command in JsFile directory:
$ npm install
  • Run tests task:
$ npm run tests

JsFile engines

Browser Support

Dependencies

Chrome Firefox Opera Safari
43+ ✔ 41+ ✔ 32✔ 8+ ✔

You can use polyfills for required API and try JsFile in older browsers.

Roadmap

Ongoing work

  • Improve performance of document parsing
  • Support .doc format
  • Add e2e tests
  • refactor zip engine

New features

  • Support .xslx format
  • Support .pptx format
  • Support .pdf
  • Support document editing and creation

Related projects

  • EasyDocs extension for browsers:

Help

You may support us:

Contribute

Guidelines

Code of conduct

JsFile is an open source project. Please read our code license

Found an Issue?

If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to our GitHub Repository. Even better you can submit a Pull Request with a fix.

Want a Feature?

You can request a new feature by submitting an issue to our GitHub Repository.

Code rules

  • All features or bug fixes must be tested by one or more specs.
  • All public API methods must be documented with jsdoc
  • We use ES6 (EcmaScript2015) in JsFile
  • See our jscs configuration

Create custom engine

See the special generator for new jsFile engine . It will help you to start and provide required dependencies, structure and tools for jsFile engine.

Installing Dependencies

Forking JsFile on Github

To create a Github account, follow the instructions here. Afterwards, go ahead and fork the main JsFile repository.

Building JsFile


#Go to the JsFile directory:
cd jsfile

#Add the main JsFile repository as an upstream remote to your repository:

git remote add upstream "https://github.com/jsFile/jsFile.git"

#Install node.js dependencies:

npm install

#Build JsFile:

grunt build

Running unit tests

npm run test

Release History

  • 2015-08-12 v0.0.1 Release of the first version

Library submitted by @webschik