www.aleph1.co.uk Git - yaffs-website/blob - node_modules/natives/README.md

   1 # natives
   2
   3 Do stuff with Node.js's native JavaScript modules
   4
   5 ## Caveat
   6
   7 Dear Beloved User,
   8
   9 I feel compelled to give you a word of warning if you are considering
  10 using this module.
  11
  12 This module lets you do some creative things with the JavaScript code
  13 in Node.js.  There are some things here that are basically a recipe
  14 for memory leaks, or at the very least, being broken with each new
  15 release of Node, since none of these API surfaces are "technically"
  16 "supported" by the team managing the Node.js project.
  17
  18 This module does not ship a _copy_ of Node's internals.  It does its
  19 thing by using the exposed source code that lives in Node.js itself.
  20 So, running this on different versions of Node.js will produce
  21 different results.
  22
  23 When your program is broken by changes to Node's internals, or when
  24 Node changes in such a way that this module becomes fundamentally
  25 broken, you will likely get little sympathy.  Many people in the Node
  26 community consider this sort of behavior to be unwise and unseemly, if
  27 not outright hostile and morally wrong.
  28
  29 At the very least, you probably just want to run Node with the
  30 (undocumented!) `--expose-internals` flag, rather than go to such
  31 lengths.
  32
  33 Don't use unless you know what you're doing, or at least, are ok with
  34 the risks.  Don't say I didn't warn you.
  35
  36 Eternally Yours in OSS,
  37 Isaac Z. Schlueter
  38
  39 ## USAGE
  40
  41 ```javascript
  42 var natives = require('natives')
  43
  44 // get the source code
  45 var fsCode = natives.source('fs')
  46
  47 // get a evaluated copy of the module
  48 var fsCopy = natives.require('fs')
  49
  50 // you can pass in a whitelist to NOT shim certain things
  51 var fsCopyWithNativeStreams = natives.require('fs', ['stream'])
  52
  53 // note that this is not the same as the "real" fs
  54 assert(fsCopy !== require('fs'))
  55
  56 // but it does have all the same entries
  57 fsCopy.readFileSync(__filename, 'utf8') // etc
  58 ```
  59
  60 ## Another Caveat
  61
  62 You can't use this to override `require("buffer")` because everything
  63 depends on `Buffer.isBuffer` working properly, so it's important for
  64 that one to be given a pass.