{"bugs":{"url":"https://github.com/dimsmol/marked_types/issues"},"dist":{"shasum":"586ae81cb7bdfba88a31c963f9a8508b38f9b316","tarball":"https://registry.npmjs.org/marked_types/-/marked_types-0.0.1.tgz","integrity":"sha512-AKsFS92tMWrQs5SL80CzugPA9jiPNrHHieuwNCj9G9O5Xe+kEn+3l3uKTS5ACD27ouy10Wy65Jpwgu9GDZ1jnA==","signatures":[{"sig":"MEQCIBcj5sykAnYnEkm2GkqVVN/Yt8ByrPPSv/o0eqPumU9RAiA4Ni1rfyu7A+s7mJgGOvk5G9d9AShKFNxYYdu5kk1oMw==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"./lib/index","name":"marked_types","_from":".","author":{"name":"Dmitry Smolin","email":"dimsmol@gmail.com"},"readme":"# Marked Types\n\nFix for instanceof issues.\n\n## The Problem\n\nUsing [npm](https://npmjs.org/) packaging you can easily get into situation when `instanceof` returns false even if object is actually an instance of given type.\n\nThis may happen when some module is loaded more than once from several different locations. It is common situation because of the way npm handles dependencies.\n\nNote, that you can run into this problem not only with npm itself, but also by using [browserify](http://browserify.org/), working with different execution contexts and possibly in number of other situations.\n\nFor more information, see [problem details](./the_problem.md).\n\n## Motivation\n\nMost cases when you want to use instanceof are simple enough:\n\n* You want to recognize certain type of objects\n\t* for example, you declared Option type and later want to check argument of some function to be an Option\n* You want to distinguish between number of types\n\t* for example, you declared several kinds of Exception subtypes and want to recognize which one you've catched.\n\nFor both cases it's enough to mark somehow your types of interest and later check objects on having corresponding markers. That's exactly what marked_types allows to do.\n\nMarked types can be used in node.js and also in browser using [browserify](http://browserify.org/) or something similar.\n\n## API\n\n* mark(type, id) - marks specified type with given id\n* is(obj, type) - checks if obj is instance of given type according to markers previously set\n\n## Type Id\n\n**NOTE** Type ids are always compared as strings for type checking purposes, without any parsing or deeper analysis. Marked types supposed to be fast, not smart. The only reason type ids have some specific format is to guarantee global uniqueness.\n\nType id format:\n\n`packageName{URI}(versionSpecifier):idWithinPackage`\n\n* `{URI}` part is optional if package is registered in [npm](https://npmjs.org/) under packageName specified, because this makes packageName unique enough\n* packageName is optional if URI is specified and already contains package name\n* `(versionSpecifier)` part is optional and can use whatever agreements you want for your package versioning\n\t* it's recommended to use version specifiers compatible with used by [npm](https://npmjs.org/)\n* `idWithinPackage` part is unique type id within your package\n\t* it can use semicolons to separate it's parts\n\t* it's recommended to use type name as idWithinPackage whenever possible\n\t* if you have several types with the same name, you can distinguish them by\n\t\t* using some \"kind specifier\" as part of idWithinPackage:\n\t\t\t* `(client):MyType`, `(server):MyType`\n\t\t* use path within package as part of idWithinPackage:\n\t\t\t* `lib/client:MyType`, `lib/server:MyType`\n\nIt's recommended to:\n\n* Use simplest form with skipping all optional parts whenever possible\n* Keep ids short but readable\n\nEscaping:\n\n* If packageName part contains \":\" (semicolon) characters, they must be escaped with \"\\\" (backslash)\n* If URI part contains \"}\" characters, they must be escaped with \"\\\" (backslash)\n* If versionSpecifier part contains \")\" characters, they must be escaped with \"\\\" (backslash)\n\nId examples:\n\n* `myPkg:MyType`\n* `myPkg:(server):MyType`\n* `myPkg:lib/client:MyType`\n* `myPkg{http://myprojectpage.com/myPkg}:(client):MyType`\n* `{http://myprojectpage.com/myOtherPkg}:(client):MyType`\n* `myPkg(>=0.1.0):MyType`\n\n## Inheritance\n\nIt works well with inherited types as far as they have correct `super_` property referencing supertype. To distinguish type from it's marked supertypes, the type itself should be marked too. See \"Usage\" and \"Internals\" below for details.\n\n## Types Versioning\n\nTypes marked with the same id are equivalent for marked_types even if they belong to different package versions. You can use versionSpecifier part to prevent this. But also you can use versionSpecifier to state that some type can be freely used across several versions.\n\nFor example:\n\n* Assume, we have package version 0.1.0 with type marked as `myPkg(0.1.0):MyType` within it\n* Then we alter version to 0.1.1 and change type id to `myPkg(>=0.1.1):MyType`\n* Then we alter version to 0.1.2 and leave type id the same\n* Then we alter version to 0.2.0 and change type id to `myPkg(>=0.2.0):MyType`\n\nThis case:\n\n* MyType types from package versions 0.1.1 and 0.1.2 will be equivalent for marked_types\n* But MyType from package version 0.1.0 will not be equivalent to ones of other versions\n* The same for version 0.2.0\n\nNote, that versionSpecifier has no direct relation to your package version. For marked_types it's just part of id and have no special meaning. But you can use it to do tricks described above.\n\n## Usage\n\nYou can mark type when it is declared:\n\n```js\nvar mt = require('marked_types');\n\nvar MyType = function () {\n};\nmt.mark(MyType, 'myPkg:MyType');\n```\n\nAnd then check if an object is instance of your type:\n\n```js\nvar obj1 = new MyType();\nmt.is(obj1, MyType); // true\nmt.is(obj1, SomeOtherType); // false\n```\n\nThis will also work for inherited types:\n\n```js\nvar inherits = require('util').inherits;\n\nvar MyOtherType = function () {\n};\ninherits(MyOtherType, MyType);\n\nvar obj2 = new MyOtherType();\n\nmt.is(obj2, MyType); // true\n// but\nmt.is(obj2, MyOtherType); // false - because MyOtherType is not marked\n```\n\nIf you want to be able to detect inherited type also, you should mark it too:\n\n```js\nvar MyThirdType = function () {\n};\ninherits(MyThirdType, MyType);\nmt.mark(MyThirdType, 'myPkg:MyThirdType');\n\nvar obj3 = new MyThirdType();\nmt.is(obj3, MyType); // true\nmt.is(obj3, MyThirdType); // true\nmt.is(obj3, MyOtherType); // false\n```\n\n## Internals\n\n`mark(type, id)` sets `typeMarker_` property of type to id specified.\n\n`is(obj, type)` gets marker of `type` or it's nearest marked supertype (if `type` itself has no marker) and returns true if the marker obtained is the same as marker of `obj.constructor` or one of it's supertypes. It uses `super_` property to get supertypes.\n\nNote, that internals can be changed in future implementations.\n\n## License\n\nMIT\n","engines":{"node":">=0.10.0"},"private":false,"_npmUser":{"name":"dimsmol","email":"dimsmol@gmail.com"},"keywords":["type","instanceof"],"repository":{"url":"https://github.com/dimsmol/marked_types","type":"git"},"_npmVersion":"1.3.2","description":"Fix for instanceof issues.","directories":{"lib":"./lib"},"maintainers":[{"name":"dimsmol","email":"dimsmol@gmail.com"}],"preferGlobal":false,"readmeFilename":"README.md","_id":"marked_types@0.0.1","version":"0.0.1"}