Merge pull request #35 from manuth/master

Add `symbol` type Workaround

README.md

@@ -298,6 +298,22 @@ interface Location {
 }
 ```
 
+### Query comments in TypeScript
+
+`comment-json` provides a `symbol`-type called `CommentSymbol` which can be used for querying comments.  
+Furthermore, a type `CommentDescriptor` is provided for enforcing properly formatted symbol names:
+
+```ts
+import { CommentDescriptor, CommentSymbol, parse } from "comment-json"
+
+const parsed = parse(`{ /* test */ "foo": "bar" }`)
+const symbolName: CommentDescriptor: "before-prop:foo"; // typescript only allows properly formatted symbol names here
+console.log(parsed[Symbol.for(symbolName) as CommentSymbol][0].value)
+```
+
+In this example, casting to `Symbol.for(symbolName)` to `CommentSymbol` is mandatory.
+Otherwise, TypeScript won't detect that you're trying to query comments.
+
 ### Parse into an object without comments
 
 ```js

index.d.ts

@@ -4,8 +4,23 @@
 // Definitions by: Jason Dent <https://github.com/Jason3S>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
+declare const commentSymbol: unique symbol
+
+export type CommentPrefix = 'before'
+  | 'after-prop'
+  | 'after-colon'
+  | 'after-value'
+  | 'after'
+
+export type CommentDescriptor = `${CommentPrefix}:${string}`
+  | 'before'
+  | 'before-all'
+  | 'after-all'
+
+export type CommentSymbol = typeof commentSymbol
+
 export class CommentArray<TValue> extends Array<TValue> {
-  [key: symbol]: CommentToken
+  [commentSymbol]: CommentToken[]
 }
 
 export type CommentJSONValue = number
@@ -17,7 +32,7 @@ export type CommentJSONValue = number
 
 export interface CommentObject {
   [key: string]: CommentJSONValue
-  [key: symbol]: CommentToken
+  [commentSymbol]: CommentToken[]
 }
 
 export interface CommentToken {

package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "test": "npm run test:only",
     "test:only": "npm run test:ts && npm run test:node",
-    "test:ts": "tsc test/ts/test-ts.ts && node test/ts/test-ts.js",
+    "test:ts": "tsc -b test/ts/tsconfig.build.json && node test/ts/test-ts.js",
     "test:node": "NODE_DEBUG=comment-json nyc ava --timeout=10s --verbose",
     "test:dev": "npm run test:only && npm run report:dev",
     "lint": "eslint .",

test/ts/test-ts.ts

@@ -5,7 +5,9 @@ import {
 
   CommentArray,
   CommentObject,
-  assign
+  assign,
+  CommentDescriptor,
+  CommentSymbol
 } from '../..'
 
 const assert = (test: boolean, message: string): void => {
@@ -33,3 +35,14 @@ assert(stringify(obj, null, 2) === `{
 }`, 'assign')
 
 assert(Array.isArray(tokenize(str)), 'tokenize')
+
+const comment = "this is a comment"
+let commentDescriptor: CommentDescriptor = `before:0`
+
+const commentSrc = `[
+  //${comment}
+  "bar"
+]`
+
+assert((parse(commentSrc) as CommentArray<string>)[Symbol.for(commentDescriptor) as CommentSymbol][0].value === comment, 'comment parse')
+commentDescriptor = "before";

test/ts/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+    "include": [],
+    "references": [
+        {
+            "path": "."
+        }
+    ]
+}

test/ts/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "compilerOptions": {
+        "module": "CommonJS",
+        "target": "ES2015"
+    },
+    "include": [
+        "./test-ts.ts"
+    ]
+}