p-hatan/ mirror

pub repository

mirror.p-hatan.ir

node_interop

2.2.0

Provides Dart bindings and utility functions for core Node.js modules.

Download archive

Readme

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:

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

Features and bugs

Please file feature requests and bugs at the issue tracker.

Changelog

2.2.0

  • Add support for fs.realpath.native() and fs.realpathSync.native().

2.1.1

  • Correctly mark the type of the undefined getter as Null.

2.1.0

  • Mark the first argument to Promise.then() as nullable.

2.0.2

  • Various fs APIs now accept options.

    • fs.appendFile, fs.mkdtemp, fs.readdir, fs.readlink, and fs.realpath, and fs.writeFile accept a FileOptions object.

    • fs.fstat and fs.lstat accept a StatOptions object.

    • fs.mkdir accepts a MkdirOptions object.

    • fs.rmdir accepts a RmdirOptions object.

    • fs.watch accepts a WatchOptions object.

    • fs.watchFile accepts a WatchFileOptions object.

    • Synchronous equivalents of the above also accept the same options.

2.0.1

  • Fix improper types for util.callbackToCompleter(), util.invokeAsync0(), and util.invokeAsync1().

2.0.0

  • Enable null-safety (requires >=Dart 2.12).

2.0.0-nullsafety.0

  • Migrated to null-safety (requires >=Dart 2.12).

1.2.1

  • Add util.callbackToCompleter(), util.invokeAsync0(), and util.invokeAsync1() helpers to make it easier to work with Node-style callbacks.

1.2.0

  • Added worker_threads module bindings (#84)
  • Added interop for Atomics (#85)

1.1.1

  • Added missing method definitions for TTYWriteStream.

1.1.0

  • Added bindings for Node.js tty module as well as updated Process bindings for stdout, stdin and stderr to return TTY stream types instead of Writable and Readable.

1.0.3

  • Removed generic annotations from Process methods per #56 (not supported by Dart yet).
  • Added util.inspect binding.

1.0.2

  • Clarified documentation of dartify regarding conversion of JS object keys (#52).

1.0.1

  • Fixed declaration of fs.writeSync and fs.readSync to return int instead of void.

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

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add node_interop
pubspec.yaml
name: node_interop
description: Provides Dart bindings and utility functions for core Node.js modules.
version: 2.2.0
homepage: https://github.com/pulyaevskiy/node-interop
author: Anatoly Pulyaevskiy <anatoly.pulyaevskiy@gmail.com>

environment:
  sdk: '>=2.12.0 <3.0.0'

dependencies:
  js: ^0.6.3

dev_dependencies:
  pedantic: ^1.0.0
  test: ^1.0.0
  build_runner: ">=1.10.0 <1.10.2"
  build_node_compilers: ^0.3.0
  build_test: ^1.0.0

Version history

VersionPublishedArchiveSHA-256
0.0.12017-06-18T02:33:05.244951ZDownload336de1a74afa547eaa5816e1b3b31f9b560c1b41951ba2196ad2d7969e618ad1
0.0.1+12017-06-18T02:41:47.575446ZDownloade3ef94857cb6e2b18e2f37424d636ea990ba908fe6ce974cad95d61d687f1b63
0.0.1+22017-06-18T04:11:11.779047ZDownloadb8f8eaf37ca6aecfa778b4bb612cb231d1815ec3a96f7e08d7ad3e5c0d3101ec
0.0.22017-06-30T19:22:38.705721ZDownloadf145eda9653cb0a4095ec8340f30c1c4b08ae57dd230eaf58e2911dbbb743cad
0.0.32017-07-02T10:19:06.570225ZDownloadaaeedf537f9810dc69c352d499ceabfd84c6e27ffeb93fd1ff4a4c533e8fe973
0.0.42017-07-08T13:44:00.731377ZDownload8ae1bb66d477729afb07c08a6098ced3d7f7198c47df1c9ec3c51b1d4d79b428
0.0.52017-10-01T04:00:03.454972ZDownload20b745bce32738f003035df1346cf25dc55cc8bf780a03f771e9ef354623981a
0.0.62017-10-03T06:55:49.794947ZDownload139767856d483cefc251255442f3843e3e2a7921d2a8837490b9e4e1049b8173
0.0.72017-10-04T06:11:56.392132ZDownload4791b2812336a427e054b9ec75746d550981ac552561fda45ae1f00b71d8ec1b
0.1.0-beta.12017-10-09T21:55:01.766303ZDownload6475ae8c33f940756974a0a1cade3d6ad59ce54ce3451a1c7e5ab5318d7d6969
0.1.0-beta.22017-10-11T04:35:39.636934ZDownload97ea197c194d22469736678cc01ed98c672d3132a75b30b5b38fe848ff93afea
0.1.0-beta.32017-10-15T00:23:23.332684ZDownloadf3d464bd26d2b3f051b5e8ffca0f9ea6fb37e3f8da0b182d5d1709cbc0e38e0d
0.1.0-beta.42017-10-17T02:48:51.904318ZDownloada1bc84026ea6094862e2244e049eeddfecfac6f610925b43b505cdcba4831f22
0.1.0-beta.52017-10-21T04:37:23.782539ZDownloada97a2e4712b6f1dec3ca14309cabd3ce0161b57336a5d8d4cd450ca5e25214de
0.1.0-beta.62017-10-22T04:14:50.120800ZDownloadaab23d3b8572a900cf9d301287582cb5e1f281da8a120eb99bae53070102c13f
0.1.0-beta.72017-12-19T17:44:39.520109ZDownload1223c15e4b80200b8f9f6d47f7e8adfbe47d4d914db38685bb0acf0d4b4e25dc
0.1.0-beta.82018-01-22T19:41:04.275553ZDownload939c15fc8fd26ffb91be9018ae8d606494aca7351609e7d097a4381fd8f3881f
0.1.0-beta.8+12018-01-22T19:50:19.739446ZDownloadaeb083e7982b967a899ef86d12ebb68444b92854809b32e692d874ac45488555
0.1.0-beta.92018-01-23T01:03:12.333448ZDownload77ccd91e12e79a93ef1f3e742bc1d95eeaeb80de29efe9db245f7f811d9bb822
1.0.0-dev.1.02018-02-09T20:23:55.364972ZDownloadaacdfe3247480fbef7b159b858145acb1ad454d8764a438db94fde1e956450a3
1.0.0-dev.1.0+12018-02-13T22:26:37.236508ZDownload0abefa798ababb5fe924dc080cadd6cd74d525db2b26b179bc5a1e88b7b436d3
1.0.0-dev.2.02018-02-14T02:43:31.560601ZDownload4889b915466d507dbd876bac57fdde919441323e93a0828ff9a89a46bba26071
1.0.0-dev.3.02018-02-20T18:12:36.925048ZDownload430bf55088510c3d32280475c4ae14e797ea651bf1b4c524d17314b00adecf66
1.0.0-dev.4.02018-03-01T20:18:26.184572ZDownload3cc53062b2d5aa62d8aba090cbe626eee27c45d77f99957af3ff5c4355748b41
1.0.0-dev.5.02018-03-07T22:11:59.712424ZDownload5c405964e6aedf433df7a2d518dbdeaec4276359770d06fed12987b1e38dd2df
1.0.0-dev.6.02018-03-08T18:50:21.105677ZDownload2f2b596967863eb723eb0887d7bdb6fcfe2a7afa18cc637873c61f49048f3796
1.0.0-dev.7.02018-06-06T19:30:37.382264ZDownloadfb3cfba49f71e1ba6d4e46eb7cdac0fa19098a98a5cb053b5aad9382f768d979
1.0.0-dev.8.02018-06-22T17:53:42.821221ZDownloadb85e4932825cc739a2d6f3673a774a4fed8dbd0b0bef103f2e33f6ea6a17b651
1.0.0-dev.9.02018-07-24T05:11:48.462189ZDownloadf630c5c3da805ed41bd3cb9e072b83ba75526025555338e4197b3702c5902c8c
1.0.0-dev.10.02018-08-09T21:11:20.384429ZDownloadac8c583aab4be3ce95624f6efc85a0f522f0259356c53191b772aaf076a8dd79
1.0.0-dev.11.02018-10-05T01:09:00.483879ZDownloada56a9c331e72adc9df0909e39f93b2c8230d26160b23b9c733a78cbaf0f3cac9
1.0.0-dev.12.02018-10-23T19:32:52.497454ZDownload936a81132d71168b4148fa1985be205f922c375ef61167f75abe564afc4f43fb
1.0.0-dev.13.02018-11-01T18:05:14.575185ZDownload4fa6e4646380caaea9f4f7c3053f4a757c62840a78c723708b9e01b1cca6c011
1.0.02018-11-20T20:33:32.317900ZDownloadb952e4801f162a9307dbd57b1ae32e214cecce96644c7d98b8d7a4b0a7270643
1.0.12019-05-09T04:04:06.549894ZDownload15e61de891f168207cb80ed0f4e23fdcae62acdef217cd4ab97e93907b16f626
1.0.22019-05-17T14:42:42.817322ZDownload0e6144bea19eea6ef0f43091806d28bbb4246face9d0a996bc5aee23860f46d6
1.0.32019-05-22T03:24:11.669434ZDownloadf4ba035f48017416979b62991fc9f4217260be5e7445d5c386bc42024783808a
1.1.02020-05-12T04:45:35.339441ZDownload9db54bead497ae71a467908267f817715fb5ea258c8ce1e91cb7799614026366
1.1.12020-05-13T04:42:26.056752ZDownload3afce5317f1071a97df98f6744be23cf67153bc91c91825fbefa3d553bdcb2e6
1.2.02020-10-30T04:39:38.681577ZDownload92499677ff249f005beacedffc1b520f7e9e3df7f8053f34c7b39d265a9788d8
1.2.12020-11-21T17:17:40.886446ZDownload910d75f8589630cd197b8b7ec70e648bc380950b489b07bda1da0c5b20c4b8c1
2.0.0-nullsafety.02021-04-12T21:30:16.447810ZDownloadfca6028f77864c843f23e9a27f3f52e670e688720bef0b597311c820e855d9f3
2.0.02021-04-12T22:27:39.013700ZDownload3b88c3931da3ea1c0fface1b4574b3a5680f689123a3350f2ec57a9a8b2224dd
2.0.12021-04-20T23:20:36.773969ZDownloadb4f93987faa4b63ac83477e4087e1923a69e0250e6437b67295bd2e1e8e5816c
2.0.22021-05-24T22:09:50.962364ZDownload0fb79f5357160e0cf28843dfcd2b34824fde9276cd810fd74862f93523337623
2.1.02021-09-22T20:09:01.294896ZDownload3af2420c728173806f4378cf89c53ba9f27f7f67792b898561bff9d390deb98e
2.2.02025-03-28T00:16:39.447905ZDownload4848ac408c0cdd0f70136b755df816a8e4c96c244e5377a3fb3b8f8950666150

Dependencies

js "^0.6.3"