Parear y encadenar JSON con comentarios. Retendrá los comentarios incluso después de guardarlos!

• Parse las cadenas JSON con comentarios en objetos JavaScript y MANTENGA los comentarios
  • soporta los comentarios en todas partes, sí, en TODAS partes en un archivo JSON, eventualmente 😆
  • fija el problema conocido sobre los comentarios dentro de las matrices.
• Cordena los objetos en cadenas JSON con comentarios si los hay

El uso de comment-json es exactamente el mismo que el del objeto vainilla JSON.

Tabla de contenidos

• Por qué y cómo
• Uso y ejemplos
• Referencia a la API
  • parse
  • cadenar
  • asignar
  • CommentArray

Cambiar registros

¿Por qué?

Hay muchas otras bibliotecas que pueden tratar con JSON con comentarios, como json5, o strip-json-comments, pero ninguna de ellas puede encadenar el objeto analizado y devolver una cadena JSON igual que el contenido original.

Imagina que si la configuración del usuario se guarda en ${library}.json， y el usuario ha escrito un montón de comentarios para mejorar la legibilidad. ¡Si la biblioteca library necesita modificar la configuración del usuario, como la modificación de algunos valores de la propiedad y la adición de nuevos campos, y si la biblioteca utiliza json5 para leer la configuración, todos los comentarios desaparecerán después de ser modificados, lo que hará que la gente se vuelva loca.

Así que, si quieres analizar una cadena JSON con comentarios, modificarla, y luego guardarla de nuevo, comment-json es tu elección obligada!

¿Cómo?

comment-json analiza las cadenas JSON con comentarios y guarda los tokens de los comentarios en las propiedades de los símbolos.

Para las matrices JSON con comentarios, comment-json extiende el objeto vanilla Array en CommentArray cuyas instancias podrían manejar los cambios de los comentarios incluso después de que una matriz de comentarios sea modificada.

Instalar

$ npm i comment-json

Para los desarrolladores de TypeScript, @types/comment-json podría utilizarse

Desde 2.4.1, comment-json contiene declaraciones de typescript, por lo que también podría eliminar @types/comment-json.

Uso

paquete.json:

{
 // package name
 "name": "comment-json"
}

Ordenar claves

Es un caso de uso común para ordenar las claves de un archivo JSON

Para más detalles sobre assign, ver aquí.

parse()

parse(text, reviver? = null, remove_comments? = false)
 : object | string | number | boolean | null

• text string La cadena a parsear como JSON. Ver el objeto JSON para una descripción de la sintaxis JSON.
• ¿reviver? Function() | null Por defecto, null. Actúa igual que el segundo parámetro de JSON.parse. Si es una función, prescribe cómo se transforma el valor producido originalmente por el análisis sintáctico, antes de ser devuelto.
• remove_comments? boolean = false Si es verdadero, los comentarios no se mantendrán, lo que se suele utilizar cuando queremos obtener un objeto limpio.

Devuelve object | string | number | boolean | null correspondiente al texto JSON dado.

Si el content es:

Y el valor de parsed será:

Hay OCHO tipos de propiedades de símbolos:

Y el valor de cada propiedad de símbolo es un array de CommentToken

interface CommentToken {
 type: 'BlockComment' | 'LineComment'
 // The content of the comment, including whitespaces and line breaks
 value: string
 // If the start location is the same line as the previous token,
 // then `inline` is `true`
 inline: boolean
 
 // But pay attention that,
 // locations will NOT be maintained when stringified
 loc: CommentLocation
}
 
interface CommentLocation {
 // The start location begins at the `//` or `/*` symbol
 start: Location
 // The end location of multi-line comment ends at the `*/` symbol
 end: Location
}
 
interface Location {
 line: number
 column: number
}

Parse en un objeto sin comentarios

console.log(parse(content, null, true))

Y el resultado será:

{
 foo: 1,
 bar: 
}

Casos especiales

const parsed = parse(`
// comment
1
`)
 
console.log(parsed === 1)
// false

Si parseamos un JSON de tipo primitivo con remove_comments:false, entonces el valor de retorno de parse() será de tipo objeto.

El valor de parsed es equivalente a:

Que es similar para:

• Boolean tipo
• String tipo

Por ejemplo

const parsed = parse(`
"foo" /* comment */
`)

Que es equivalente a

Pero hay una excepción:

const parsed = parse(`
// comment
null
`)
 
console.log(parsed === null) // true

stringify()

stringify(object: any, replacer?, space?): string

Los argumentos son los mismos que la vainilla JSON.stringify.

Y hace lo mismo que la vanilla, pero además trata con propiedades extra y las convierte en comentarios.

console.log(stringify(parsed, null, 2))
// Exactly the same as `content`

space

Si no se especifica el espacio, o el espacio es una cadena vacía, el resultado de stringify() no tendrá comentarios.

Para el caso anterior:

console.log(stringify(result)) // {"a":1}
console.log(stringify(result, null, 2)) // is the same as `code`

assign(target: object, source?: object, keys?: Array)

• target object the target object
• source? object el objeto de origen. Este parámetro es opcional pero es una tontería no pasar este argumento.
• ¿claves? Array<string> Si no se especifica, se utilizarán todas las propiedades propias enumerables de source.

Este método se utiliza para copiar las propiedades propias enumerables y sus correspondientes propiedades de símbolo de comentario al objeto destino.

Casos especiales sobre claves

Pero si se especifica el argumento keys y no está vacío, entonces el comentario before all, que no pertenece a ninguna propiedad, NO se copiará.

const obj = assign({
 bar: 'baz'
}, parsed, )
 
stringify(obj, null, 2)
// {
// "bar": "baz",
// // This is a comment
// "foo": "bar"
// }

Especificar el argumento keys como una matriz vacía indica que sólo copiará los símbolos no pertenecientes a propiedades de los comentarios

const obj = assign({
 bar: 'baz'
}, parsed, )
 
stringify(obj, null, 2)
// // before all
// {
// "bar": "baz",
// }

Los símbolos no pertenecientes a propiedades incluyen:

Symbol.for('before-all')
Symbol.for('before')
Symbol.for('after-all')

CommentArray

Sección avanzada

Todas las matrices del objeto analizado son CommentArrays.

Se podría acceder al constructor de CommentArraypor:

const {CommentArray} = require('comment-json')

Si modificamos un array de comentarios, sus propiedades de símbolos de comentarios podrían manejarse automáticamente.

¡Oh sí! 😆

Pero atención, si reasignamos la propiedad de un array de comentarios con un array normal, todos los comentarios desaparecerán:

En su lugar, deberíamos:

Casos especiales sobre la coma final

Si tenemos una cadena JSON str

.