Typescript types as index.d.ts file please

[nojvek]

Great library, although the interface is somewhat unintuitive. Is isValid the only method?

Would love to see typescript types so the library interface is fully documented. I can help here. Just don't really know what the interface right now is, and how to make most of the library.

[luizperes]

Hi @nojvek, fair point. I was taking a look at the readme and realized it could be a little more clear.

I will try to explain here a little better and will use that to change the README later. Please consider the the section Usage of the README.

As I tried to show in the README, this simdjson wrapper has only three functions: isValid, parse and lazyParse. I will explain the rationale behind all of them.

isValid

• doc: Checks whether or not a json string is valid. It is a very very fast operation, since it is only a validation in parallel of a json string. It validates the documents, but doesn't necessarily parses it (such as numbers and etc).
• type: (jsonString: string) => boolean

parse

• doc: Constructs a JavaScript object described by the JSON string that is given as input. This does the same as the standard JSON.parse as well as have the same signature.
• type: (jsonString: string) => JSONDataType
• observation: This method is not preferable because there exists a lot of overhead in the conversion of C++ data into JS data (package node-addon-api). For more details, check issue Parsing time is dominated by makeJSONObject (in the wrapper) #5

lazyParse

• doc: Parses a JSON string but does not construct a JavaScript object. Instead, it keeps the pointer to the external (C++) parsed JSON. This method is preferable because it allows the developer to use the full power of simdjson (with the same parsing speed as the upstream), while still avoiding the overhead of constructing a full JavaScript object and focusing on lazily constructing only important pieces of the parsed object. Issue Parsing time is dominated by makeJSONObject (in the wrapper) #5 has a very detailed explanation of this problem.
• type: (jsonString: string) => LazyParsedJson
• observation: You can only access the parsed object (since it is a C++ external object) through the function valueForKeyPath, which is similar to the NSObject valueForKeyPath

where:

type JSONDataType: is any of { string, number, object, array, boolean, null }

interface LazyParsedJSON {
    valueForKeyPath: (keyPath: string) => JSONDataType
}

I hope this is a little better than the current documentation. See that the type JSONDataType and interface LazyParsedJSON would not necessarily be reflected in TypeScript, but I hope that it helps it to make the project a little more clear. Also, see that the wrapper is in simdjson version 0.2.1 and @lemire has updated it to version 0.3 and I am working so to update the node library (issues #24, #23 and #3). So if you can help here, your work would really be appreciated!

Cheers,
Luiz

[luizperes]

I've moved what I explained here to the file Documentation.md

[nojvek]

Sweeet. I will take a pass tomorrow.

[luizperes]

Closing this as PR #30 addresses that, thank you for your work @nojvek!