node_interop 1.0.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 83

Node Interop Build Status Pub Gitter

Write applications in Dart, run in NodeJS.

Looking for latest updates? Make sure to check the most recent 1.0.0-dev.* release!

What is this?

This library provides JavaScript bindings and some utilities to work with core Node APIs and built-in modules.

To compile Dart applications as Node modules see build_node_compilers package.

For a more Dart-like experience with Node I/O system see node_io package which is designed as a drop-in replacement for dart:io.

For a Dart-style HTTP client checkout node_http.

Example

Here is an example Node app written in Dart:

import 'package:node_interop/node.dart';

void main() {
  print("Hello world, I'm currently in ${process.cwd()}.");
}

This application can be compiled with build_node_compilers and executed in Node.

For more examples using different APIs see example/ folder.

Structure

For each built-in Node module there is a separate Dart file in the lib/ folder. So to access Node's os module, for instance, you'd need to use following import:

import 'package:node_interop/os.dart';

Note that after importing a module like above there is no need to also require it (the Node way). Each library file (like os.dart) exposes library-level property of the same name which gives you access to that module's functionality. This is just a convenience to not have to import and require modules at the same time. Here is how os.dart implements it:

// file:lib/os.dart
@JS()
library node_interop.os;

import 'package:js/js.dart';

import 'node.dart';

OS get os => require('os');

@JS()
@anonymous
abstract class OS {
  external List<CPU> cpus();
  // ...
}

Not all built-in Node modules need to be required, like buffer module for instance. They still have a dedicated Dart file in this library, but this is mostly for consistency and you shouldn't need to import it directly. The buffer module is globally available in Node.

Libraries with underscores in their name (like child_process) expose library-level property with underscores converted to camelCase to be compliant with Dart code style rules:

import 'package:node_interop/child_process.dart';

void main() {
  childProcess.execSync('ls -la');
}

Note on creating native Node.js objects

Most of the objects in Node.js are not global therefore they are declared as @anonymous in this library. Unfortunately this prevents us from instantiating new instances by simply using new Something().

As a workaround for this problem each module provides a createX() library function. For instance, stream module provides createReadable and createWritable for creating custom Readable and Writable streams:


import 'dart:js_util'; // provides callConstructor()

/// The "stream" module's object as returned from [require] call.
StreamModule get stream => _stream ??= require('stream');
StreamModule _stream;

@JS()
@anonymous
abstract class StreamModule {
  /// Reference to constructor function of [Writable].
  dynamic get Writable;

  /// Reference to constructor function of [Readable].
  dynamic get Readable;
}

/// Creates custom [Writable] stream with provided [options].
///
/// This is the same as `callConstructor(stream.Writable, [options]);`.
Writable createWritable(WritableOptions options) {
  return callConstructor(stream.Writable, [options]);
}

Status

Version 1.0.0 is considered stable though not feature complete. It is recommended to check 1.0.0-dev.* versions for latest updates and bug fixes.

Make sure to checkout CHANGELOG.md after every release, all notable changes and upgrade instructions will be described there.

If you found a bug, please don't hesitate to create an issue in the issue tracker.

Below is a list of built-in Node.js modules this library already provides bindings for:

  • [x] buffer
  • [x] child_process
  • [ ] cluster
  • [x] console
  • [x] dns
  • [ ] domain
  • [x] events
  • [x] fs
  • [x] http
  • [x] https
  • [x] module
  • [x] net
  • [x] os
  • [x] path
  • [x] process
  • [x] querystring
  • [ ] readline
  • [x] stream
  • [ ] string_decoder
  • [x] timers
  • [x] tls
  • [ ] tty
  • [ ] dgram
  • [ ] url
  • [ ] util
  • [ ] v8
  • [ ] vm
  • [ ] zlib

Features and bugs

Please file feature requests and bugs at the issue tracker.

1.0.0

No functional changes in this version, it is published to replace obsolete 0.0.7 version on the Pub's package homepage to improve discoverability.

Ongoing work will continue in 1.0.0-dev.* branch until it's considered stable and feature complete. Make sure to checkout recent dev version for latest updates.

Non-breaking changes may be published to the stable track periodically.

1.0.0-dev.13.0

  • Added HttpsAgentOptions with basic TLS/SSL parameters.
  • Breaking: createHttpsAgent() now expects instance of HttpsAgentOptions instead of HttpAgentOptions.

1.0.0-dev.12.0

  • Fixed Console method bindings to not force String arguments and allow any type.
  • Breaking: Updated JsError constructor definition to match Node.js documentation.

1.0.0-dev.11.0

  • Upgraded to build_node_compilers 0.2.0

1.0.0-dev.10.0

  • Internal changes.

1.0.0-dev.9.0

  • Fixed analysis warnings.

1.0.0-dev.8.0

  • Upgraded to latest build_node_compilers.

1.0.0-dev.7.0

  • Fixed: Changed ServerResponse.getHeader return type from String to dynamic.

1.0.0-dev.6.0

  • Added: binding for JS undefined value in node_interop/js.dart.

1.0.0-dev.5.0

  • Fixed: strong mode issue in dartify utility function when converting plain JS objects to Dart Map. Returned map is now of type Map<String, dynamic> instead of Map.

1.0.0-dev.4.0

  • Fixed: strong mode issue in promiseToFuture utility function.
  • Fixed: signature of fs.realpathSync.

1.0.0-dev.3.0

  • Added or completed bindings for following Node.js modules: dns, events, fs, http, https, module, net, os, path, process, querystring, stream, timers, tls.
  • Added more examples and tests.

1.0.0-dev.2.0

  • Completed dns module function definitions (still missing data structures).

1.0.0-dev.1.0+1

  • Minor internal changes.

1.0.0-dev.1.0

Breaking changes:

  • node_interop depends on Dart 2 SDK which allows us to leverage new build_runner system and move away from Pub transformers.
  • Removed Pub transformer, which means you shouldn't need it in your pubspec.yaml anymore. Build system is now based on build package. See docs for more details.
  • node_interop no longer exports Dart-specific abstractions like an HTTP client or FileSystem. These abstractions have been moved to separate packages: node_io and node_http. This way node_interop now only exposes JS bindings for Node and some utility functions.
  • library structure is changed to map closer to built-in Node modules. There is a separate file for each module which exposes that module's bindings, e.g. fs.dart, http.dart.
  • node object has been removed. Can use require and exports functions directly. There is also new convenience function setExport.
  • jsPromiseToFuture renamed to promiseToFuture.
  • futureToJsPromise renamed to futureToPromise.
  • jsObjectKeys renamed to objectKeys.
  • dartify now allows converting JS function objects.
  • `JsPromise

0.1.0-beta.9

  • Added library-level get function to http.dart.

0.1.0-beta.8+1

  • Updated changelog.

0.1.0-beta.8

  • Introduced new io.dart library designed to follow dart:io contract.
  • Breaking: renamed HttpRequest exposed by http.dart to NodeHttpRequest. This is a server-side request object which will eventually be hidden from this library. It is recommended to import new io.dart which exposes both HttpRequest and NodeHttpRequest objects.

0.1.0-beta.7

  • Fix HttpHeaders.forEach crash when called on HttpRequest.headers [#6]

0.1.0-beta.6

  • Breaking:
    • renamed ReadableStream.nativeStream to ReadableStream.nativeInstance
    • renamed WritableStream.nativeStream to WritableStream.nativeInstance
  • New:
    • Added jsonStringify and jsonParse which bind to native JSON.stringify and JSON.parse respectively.

0.1.0-beta.5

  • Fixed: HttpResponse.close() failed when trying to finalize headers.

0.1.0-beta.4

  • Made Promise<T> a generic type. Also added definition of Thenable.
  • onRejected in Promise.then is now optional.
  • Added explicit type to node variable.

0.1.0-beta.3

  • More updates to bindings.
  • Added new async.dart library with basic implementations of ReadableStream<T>, WritableStream<T> and NodeIOSink.
  • Added implementations of server side HttpRequest and HttpResponse to http.dart, as well some other objects like HttpHeaders.
  • Added dartifyError(JsError error) to the main library which converts from JS Error instances in to Dart's equivalent.
  • Implemented more methods in File: openRead, openWrite, readAsBytes.
  • Deprecated createJSFile in test.dart library. Use createFile instead.

0.1.0-beta.2

  • jsObjectToMap deprecated. There is new helper function dartify. See documentation for more details.
  • New jsify helper function.
  • Clarified type of HTTP server requestListener.
  • New createJSFile test util in test.dart.

0.1.0-beta.1

  • Breaking changes:
    • NodePlatform is no longer exported from node_interop.dart library.
    • Library-level exports getter was removed. Now exports is a direct reference to native JS object. Replace any calls to exports.setProperty(name, value) with new API: node.export(name, value).
    • "http" module: Agent, Server, AgentOptions renamed to HttpAgent, HttpServer, HttpAgentOptions respectively.
    • "http" module: createAgent renamed to createHttpAgent.
    • node_interop/bindings.dart was removed. All bindings are available through main node_interop/node_interop.dart import.
  • New:
    • Many updates to documentation.
    • Main package's library now exposes all (implemented) Node API bindings.
    • New node library object with centralized access to the Node platform and runtime information, as well as module globals like require and exports.
    • Exposed parts of "https", "tls", "dns" and "net" module bindings.
    • Added HTTPS support to NodeClient from node_interop/http.dart.
    • Updated examples.
    • Gitter channel is now up: https://gitter.im/pulyaevskiy/node-interop.

0.0.7

  • Added node_interop/test.dart library with installNodeModules() helper function. See dartdoc for more details.

0.0.6

  • jsObjectToMap: added null-check.
  • Added basic HTTP client implementation for Node, based on an interface from 'http' package. Use with import package:node_interop/http.dart.

0.0.5

  • Streamlined bindings layer and exposed as it's own library. Use import package:node_interop/bindings.dart to get access.
  • Added bindings for 'http' module (work in progress).

0.0.4

  • Upgraded to test package with support for running tests in Node
  • Implemented NodeFileSystem.file() and File.writeAsStringSync().

0.0.3

  • Added bindings for Console.

0.0.2

  • Switched to use official node_preamble package

0.0.1

  • Initial version

example/README.md

Building examples

From the root of this repository:

pub run build_runner build --output=build/

Running examples

Look for build/example/{example_name}.dart.js file and run it with node:

node build/example/{example_name}.dart.js

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  node_interop: ^1.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:node_interop/node_interop.dart';
  
Version Uploaded Documentation Archive
1.0.0 Nov 20, 2018 Go to the documentation of node_interop 1.0.0 Download node_interop 1.0.0 archive
0.0.7 Oct 4, 2017 Go to the documentation of node_interop 0.0.7 Download node_interop 0.0.7 archive
0.0.6 Oct 3, 2017 Go to the documentation of node_interop 0.0.6 Download node_interop 0.0.6 archive
0.0.5 Oct 1, 2017 Go to the documentation of node_interop 0.0.5 Download node_interop 0.0.5 archive
0.0.4 Jul 8, 2017 Go to the documentation of node_interop 0.0.4 Download node_interop 0.0.4 archive
0.0.3 Jul 2, 2017 Go to the documentation of node_interop 0.0.3 Download node_interop 0.0.3 archive
0.0.2 Jun 30, 2017 Go to the documentation of node_interop 0.0.2 Download node_interop 0.0.2 archive
0.0.1+2 Jun 18, 2017 Go to the documentation of node_interop 0.0.1+2 Download node_interop 0.0.1+2 archive
0.0.1+1 Jun 18, 2017 Go to the documentation of node_interop 0.0.1+1 Download node_interop 0.0.1+1 archive
0.0.1 Jun 18, 2017 Go to the documentation of node_interop 0.0.1 Download node_interop 0.0.1 archive

All 34 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
65
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
83
Learn more about scoring.

We analyzed this package on Dec 5, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.7

Platforms

Detected platforms: web, other

Primary library: package:node_interop/node_interop.dart with components: js.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0
js ^0.6.1 0.6.1+1
Dev dependencies
build_node_compilers ^0.2.0
build_runner ^1.0.0
build_test any
test ^1.0.0