{"_id":"kaiser","_rev":"8-2e372ac3dfe929ef3678475beb7fff59","name":"kaiser","description":"Serialization of arbitrary objects","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.0":{"name":"kaiser","description":"Serialization of arbitrary objects","version":"0.0.0","format":"cjs","repository":{"type":"git","url":"git+https://github.com/breuleux/kaiser.git"},"keywords":[],"author":{"name":"Olivier Breuleux"},"license":"MIT","main":"./lib/index.js","dependencies":{"earlgrey-runtime":">=0.0.10"},"devDependencies":{"earlgrey":">=0.0.10","mocha":"^2.2.1","earl-mocha":">=0.0.2"},"scripts":{"refresh":"earl compile -5vso lib/ src/","compile":"earl compile -5rvso lib/ src/","prepublish":"npm run compile","test":"mocha"},"gitHead":"d343e86eca624435f00230a6c3ebb359980f5b42","bugs":{"url":"https://github.com/breuleux/kaiser/issues"},"homepage":"https://github.com/breuleux/kaiser#readme","_id":"kaiser@0.0.0","_shasum":"8b111d4ab41e0b656020188d0a7c3c657395cecd","_from":".","_npmVersion":"2.11.2","_nodeVersion":"0.12.6","_npmUser":{"name":"breuleux","email":"breuleux@gmail.com"},"maintainers":[{"name":"breuleux","email":"breuleux@gmail.com"}],"dist":{"shasum":"8b111d4ab41e0b656020188d0a7c3c657395cecd","tarball":"https://registry.npmjs.org/kaiser/-/kaiser-0.0.0.tgz","integrity":"sha512-z7uds88hSDmDdBMg9NdlQIHIlCjP3DlD/VJwPNMhH2hShzgIRIh3al6ZwbQRu+eK94iWwwDarBhJTVUA6fuRog==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCCkBAkQRWcBU8+nTPIHyw8efCnSKRZmTJGxmy0idVT9AIhAJNQ4+hx/CxkngrmUeb+6YhqpZmPGCJ4fOuZLytwVXoh"}]}},"0.0.1":{"name":"kaiser","description":"Serialization of arbitrary objects","version":"0.0.1","format":"cjs","repository":{"type":"git","url":"git+https://github.com/breuleux/kaiser.git"},"keywords":[],"author":{"name":"Olivier Breuleux"},"license":"MIT","main":"./lib/index.js","dependencies":{"earlgrey-runtime":">=0.0.10"},"devDependencies":{"earlgrey":">=0.0.12","mocha":"^2.2.1","earl-mocha":">=0.0.2"},"scripts":{"refresh":"earl compile -5vso lib/ src/","compile":"earl compile -5rvso lib/ src/","prepublish":"npm run compile","test":"mocha"},"gitHead":"aa678274869a9a768a09d7dc8950867e76206398","bugs":{"url":"https://github.com/breuleux/kaiser/issues"},"homepage":"https://github.com/breuleux/kaiser#readme","_id":"kaiser@0.0.1","_shasum":"9dae2cb5dd1effb53ab8eb38a7ac5457f5dff46c","_from":".","_npmVersion":"2.11.2","_nodeVersion":"4.0.0","_npmUser":{"name":"breuleux","email":"breuleux@gmail.com"},"maintainers":[{"name":"breuleux","email":"breuleux@gmail.com"}],"dist":{"shasum":"9dae2cb5dd1effb53ab8eb38a7ac5457f5dff46c","tarball":"https://registry.npmjs.org/kaiser/-/kaiser-0.0.1.tgz","integrity":"sha512-fWmwsE3lpNxvEETufhkicFut5FvslpC96+j2aApbYjx/3Dw+sVqAhlvFS9McEqU1FCJYst7rIgEG4XmCLO+Lzg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHV/gsdaDRRLOXoA2/a6lwUXr7+8UPEFXUHToFuZy2+EAiB+FVag8CVbYrImubYdwV0mEnA5AGXm6q1LNVLsybGWxQ=="}]}},"0.0.2":{"name":"kaiser","description":"Serialization of arbitrary objects","version":"0.0.2","format":"cjs","repository":{"type":"git","url":"git+https://github.com/breuleux/kaiser.git"},"keywords":["serialization","serialize","deserialize"],"author":{"name":"Olivier Breuleux"},"license":"MIT","main":"./lib/index.js","dependencies":{"earlgrey-runtime":">=0.0.10"},"devDependencies":{"earlgrey":">=0.0.12","mocha":"^2.2.1","earl-mocha":">=0.0.2"},"scripts":{"refresh":"earl compile -5vso lib/ src/","compile":"earl compile -5rvso lib/ src/","prepublish":"npm run compile","test":"mocha"},"gitHead":"75ec24303501fa263ce0516ddfce426b4534123b","bugs":{"url":"https://github.com/breuleux/kaiser/issues"},"homepage":"https://github.com/breuleux/kaiser#readme","_id":"kaiser@0.0.2","_shasum":"a8a26460cc216a8a58adca749034a28611ada72a","_from":".","_npmVersion":"2.11.2","_nodeVersion":"4.0.0","_npmUser":{"name":"breuleux","email":"breuleux@gmail.com"},"maintainers":[{"name":"breuleux","email":"breuleux@gmail.com"}],"dist":{"shasum":"a8a26460cc216a8a58adca749034a28611ada72a","tarball":"https://registry.npmjs.org/kaiser/-/kaiser-0.0.2.tgz","integrity":"sha512-EKf+Ny1tD8NgyowInRVTv4OcGpORvHNjFJys0TUcc6Jl/TtFaGiqtqVhtWlUI5b3fN0tSufrow7YYYDlQeCAqg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICOLeVmd3z101zz0N3KErfZkd4XXYs5eBtNxUthPe8JRAiBd0ZBN51DNWBAWKsGY3dAE86uAFImw2xkqGKnwXg/IAw=="}]}},"0.0.3":{"name":"kaiser","description":"Serialization of arbitrary objects","version":"0.0.3","format":"cjs","repository":{"type":"git","url":"git+https://github.com/breuleux/kaiser.git"},"keywords":["serialization","serialize","deserialize"],"author":{"name":"Olivier Breuleux"},"license":"MIT","main":"./lib/index.js","dependencies":{"earlgrey-runtime":">=0.0.10"},"devDependencies":{"earlgrey":">=0.0.12","mocha":"^2.2.1","earl-mocha":">=0.0.2"},"scripts":{"refresh":"earl compile -5vso lib/ src/","compile":"earl compile -5rvso lib/ src/","prepublish":"npm run compile","test":"mocha"},"gitHead":"4976403e952d9018048b9fca3d93289ae78fe6c8","bugs":{"url":"https://github.com/breuleux/kaiser/issues"},"homepage":"https://github.com/breuleux/kaiser#readme","_id":"kaiser@0.0.3","_shasum":"3cc9a7941488f2bc45be7012504226cee738390a","_from":".","_npmVersion":"2.11.2","_nodeVersion":"4.0.0","_npmUser":{"name":"breuleux","email":"breuleux@gmail.com"},"maintainers":[{"name":"breuleux","email":"breuleux@gmail.com"}],"dist":{"shasum":"3cc9a7941488f2bc45be7012504226cee738390a","tarball":"https://registry.npmjs.org/kaiser/-/kaiser-0.0.3.tgz","integrity":"sha512-XwQ8pE5YyUQo0HSWXLdGtpZMs8X0hDNlJVmd5j3lwYiyAbNcR8Wd7f4zJJBSkdznxShkGwCWcAmMqnsEwyZg/Q==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIHDmbEMqBG5dj7on4nwWMGNStw6ppiJJAZYuk1TfrhYDAiEA/3JM6lRZ6454TgkhUcwhd4jOYBzGRkwXLTNn12HKZh0="}]}},"0.0.4":{"name":"kaiser","description":"Serialization of arbitrary objects","version":"0.0.4","format":"cjs","repository":{"type":"git","url":"git+https://github.com/breuleux/kaiser.git"},"keywords":["serialization","serialize","deserialize"],"author":{"name":"Olivier Breuleux"},"license":"MIT","main":"./lib/index.js","dependencies":{"earlgrey-runtime":">=0.0.10"},"devDependencies":{"earlgrey":">=0.0.12","mocha":"^2.2.1","earl-mocha":">=0.0.2"},"scripts":{"refresh":"earl compile -5vso lib/ src/","compile":"earl compile -5rvso lib/ src/","prepublish":"npm run compile","test":"mocha"},"gitHead":"4874c92c54b3ff6df16485f9a86342fc85e10921","bugs":{"url":"https://github.com/breuleux/kaiser/issues"},"homepage":"https://github.com/breuleux/kaiser#readme","_id":"kaiser@0.0.4","_shasum":"d25ddf800640857fadde08dba59ffc7a5a4f5c38","_from":".","_npmVersion":"2.11.2","_nodeVersion":"4.0.0","_npmUser":{"name":"breuleux","email":"breuleux@gmail.com"},"maintainers":[{"name":"breuleux","email":"breuleux@gmail.com"}],"dist":{"shasum":"d25ddf800640857fadde08dba59ffc7a5a4f5c38","tarball":"https://registry.npmjs.org/kaiser/-/kaiser-0.0.4.tgz","integrity":"sha512-m8ju+rmBqvclZmyrOXgGGhOYSjKJK6RN1NhqEltemY87UqZOxEkizg9TOy1vQSyJ01Wx6SAPuuN0iO2Mgislvw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIAEjOfmSx/J2p/CsaSFKypmsisoTNoNEfSnhB/XoGlfkAiAlNLUIVPX1ppLYr1UfaUJgwisyK5gFtBgSYEZgWCKMhQ=="}]}}},"readme":"\nkaiser\n======\n\nSerialization library that allows arbitrary objects and classes to be\nserialized or deserialized in a safe way.\n\nkaiser can serialize standard JavaScript data, objects, arrays and\ndates out of the box.\n\nHowever, kaiser is not *magical*. Any non-native object type has to be\nregistered with a type id (ideally a uuid), a serializer and a\ndeserializer.\n\n* **General**: kaiser can be configured to serialize and deserialize\n  any data.\n\n* **Powerful**: object identity is preserved by deserialization.\n  Circular references can be handled.\n\n* **Safe(ish)**: the deserializer can be configured to only\n  deserialize objects from a whitelist. This is safe as long as the\n  serializers in the whitelist are safe.\n\n* **Low registration overhead**: packages can register custom\n  serializers for their classes and functions using `kaiser/reg`,\n  which is about 300 bytes minified.\n\n* **Other uses**: kaiser can be used to make shallow or deep copies of\n  objects.\n\nThe `kaiser` package in and of itself is fairly large for what it\ndoes, mostly because it is written in Earl Grey, which comes with some\noverhead. I plan to address that eventually.\n\n\nUsage\n-----\n\nSimple serialization/deserialization\n\n```javascript\nvar kaiser = require(\"kaiser\");\nvar str = kaiser.serialize({a: 1, b: new Date()});\nvar obj = kaiser.deserialize(str);\n```\n\n### whitelists\n\nYou can also instantiate a `Serializer` object with a whitelist, which\nmeans only a limited list of approved objects and classes can be\nserialized or deserialized. The resulting serializer, when used on\nunsanitized data, will be as safe as the most unsafe object in the\nwhitelist, so be careful:\n\n```javascript\nvar kaiser = require(\"kaiser\");\nvar s = kaiser.Serializer([Date, Person]);\n\nvar str1 = ser.serialize({a: new Date(), b: new Person()}); // OK!\nvar obj2 = ser.deserialize(str1);                           // OK!\n\nvar str2 = ser.serialize({a: 1, b: new Animal()});          // ERROR!\n\nvar str3 = kaiser.serialize({a: 1, b: new Animal()});       // OK (generic serializer)\nvar obj3 = ser.deserialize(str3);                           // ERROR!\n```\n\n\nRegistering functionality\n-------------------------\n\nTo register with `kaiser` you need to assign a uuid to your class or\nfunction. A uuid is a unique symbol which can identify your\nfunctionality in any application that imports it and will not clash\nwith any other package. There are a few ways to do it, and `kaiser`\ncan help you.\n\nFirst you must import `kaiser`, for that you have two options:\n\n```javascript\n// Option A: Import the full package\nkaiser = require(\"kaiser\");\n\n// Option B: Import only the registering functions\nkaiser = require(\"kaiser/reg\");\n```\n\nThe difference between the two is that option B only defines a few\nstubs to let you register your classes for serialization and is about\n300 bytes minified, so it is super cheap if you only want to provide\nthe functionality to people who need it. Then when they import the\nfull `kaiser` package, the serializers will get registered for real.\n\nNow, suppose you have the following definition:\n\n```javascript\nfunction Vehicle(brand) {\n    this.brand = brand;\n}\nVehicle.prototype.start = function () {\n    console.log(\"vroom vroom!\");\n}\n```\n\n\n### Use package info\n\nThis will assign `Vehicle` the uuid `npm:my-package/Vehicle`:\n\n```javascript\nkaiser.register(Vehicle.prototype, {\n    package: {name: \"my-package\", \"version\": \"1.2.3\"}\n});\n```\n\nThis will assign `Vehicle` the uuid `npm:my-package@1/Vehicle`:\n\n```javascript\nkaiser.register(Vehicle.prototype, {\n    package: {name: \"my-package\", \"version\": \"1.2.3\"},\n    useVersion: \"major\"\n});\n```\n\nOf course, if you have a `package.json` file in the same directory,\nyou should simply do this:\n\n```javascript\nkaiser.register(Vehicle.prototype, {\n    package: require(\"./package.json\"),\n    useVersion: \"minor\"\n});\n```\n\nTo register more than one class, use `kaiser.registerAll`:\n\n```javascript\nkaiser.registerAll([Vehicle.prototype, Animal.prototype], {\n    package: require(\"./package.json\"),\n    useVersion: \"minor\"\n});\n```\n\n### uuid\n\nInstall the `uuid` command on your system and run it. It will give you\na (presumably) unique hexadecimal identifier that you can paste in\nyour code:\n\n```bash\n$ uuid\nbfd249d8-302a-11e5-8044-278351ad39e9\n```\n\nThen you must set the `typeId` field:\n\n```javascript\nkaiser.register(Vehicle.prototype, {\n    typeId: \"bfd249d8-302a-11e5-8044-278351ad39e9\"\n});\n```\n\n`kaiser.registerAll` can be used with just one `typeId`. What it will\ndo is that it will generate ids like\n`bfd249d8-302a-11e5-8044-278351ad39e9/Vehicle` and so on.\n\n\n### uuid interface\n\nIn order to generate a uuid, `kaiser` follows these steps:\n\n* If the configuration object contains:\n* `typeId` and `variant`: `typeId + JSON.stringify(variant)`\n* `typeId` and `nameVariant === true`: `typeId + object.name`\n* `typeId` and `nameVariant`: `typeId + nameVariant`\n* `typeId`: `typeId`\n* `package` and `useVersion`: `package@version/object.name`\n\nNote that `registerAll` and `registerSingletons` automatically set\n`nameVariant` in order to differentiate the entries. It is thus\nimportant that they all have names.\n\n\nRegistering functions and singletons\n------------------------------------\n\nBy default, `kaiser` understands that what is being registered is a\nprototype, and that objects that directly inherit from the prototype\nare those that we wish to serialize.\n\nOn the other hand, you may want to serialize functions, or objects\nas-is. To that purpose you may use `kaiser.registerFunction` or\n`kaiser.registerSingleton` (they are the same thing). Both functions\nhave a plural equivalent that lets you register more than one thing at\nonce.\n\n```javascript\nfunction hello(name) {\n    return \"hello, \" + name\n}\nfunction bye(name) {\n    return \"bye, \" + name\n}\n\nkaiser.registerSingletons([hello, bye], {\n    package: require(\"./package.json\"),\n    useVersion: \"patch\"\n});\n```\n\nThe above will registers ids `\"npm:my-package@1.2.3/hello\"` and\n`\"npm:my-package@1.2.3/bye\"`.\n\n\nCustom serialization\n--------------------\n\nBy default `kaiser.serialize` will pack all the fields in an object\nand `kaiser.deserialize` will instantiate an object with the right\nprototype and write the fields back.\n\nBut you can change this. Here is a simple example (of a flawed\nserialization mechanism):\n\n```javascript\nkaiser.register(Person.prototype, {\n    typeId: \"bfd249d8-302a-11e5-8044-278351ad39e9\",\n    serialize: function (person) {\n        return person.name + \"/\" + person.age;\n    },\n    deserialize: function (person) {\n        fields = person.split(\"/\");\n        return new Person(fields[0], parseInt(fields[1]));\n    }\n});\n```\n\nThe serialization and deserialization interface is as follows:\n\n**`serialize(object)`** must return either some primitive type like a\nString or Number, or a plain object or array in which the fields are\n*not serialized* (in other words, do not call `kaiser.serialize` in\nthat function). `kaiser` will serialize these fields for you so that\nyou can focus on the logic.\n\n**`deserialize(form)`** must rebuild the object previously serialized\nexactly. It will receive the same output serialize produced, with\nalready deserialized fields (do not call `kaiser.deserialize` in that\nfunction).\n\nIn addition, the following two methods must be implemented to support\ncircular references for your type:\n\n**`create()`** must return an instance of the object.\n\n**`fill(target, form)`** must fill the return value of `create` so\nthat `target` becomes the deserialized `form`.\n\nTo put it simply, `var r = create(); fill(r, x)` must be equivalent to\n`var r = deserialize(x)`.\n\n","maintainers":[{"name":"breuleux","email":"breuleux@gmail.com"}],"time":{"modified":"2022-06-19T07:44:48.420Z","created":"2015-08-01T00:53:20.629Z","0.0.0":"2015-08-01T00:53:20.629Z","0.0.1":"2015-09-15T04:57:18.817Z","0.0.2":"2015-09-17T04:15:16.511Z","0.0.3":"2015-10-26T03:42:45.276Z","0.0.4":"2016-01-25T21:49:11.585Z"},"homepage":"https://github.com/breuleux/kaiser#readme","keywords":["serialization","serialize","deserialize"],"repository":{"type":"git","url":"git+https://github.com/breuleux/kaiser.git"},"author":{"name":"Olivier Breuleux"},"bugs":{"url":"https://github.com/breuleux/kaiser/issues"},"license":"MIT","readmeFilename":"README.md","users":{"realazthat":true}}