Parse, validate and stringify metadata in TypeScript.
npm install @monoid-dev/userscript-metadataParse, validate and stringify metadata in TypeScript.
```
npm install --save typescript userscript-metadata
This example demonstrates how metadata can be defined, validated and stringified:
`typescript
import {
Kind, Metadata, ValidationError,
isRight, validateAndStringify,
} from "userscript-metadata";
const metadata: Metadata = {
name: "Example Userscript",
version: "1.0.0",
match: [
://example.com/,://www.example.com/
,
],
run_at: "document-start",
noframes: true,
};
function stringifyError(error: ValidationError): string {
switch (error.kind) {
case Kind.INVALID_KEY: return Invalid key: "${error.entry.key}". ${error.reason};Invalid @${error.entry.key} value: ${JSON.stringify(error.entry.value)}. ${error.reason}
case Kind.INVALID_VALUE: return ;Multiple @${error.item.key} values. Only one value is allowed.
case Kind.MULTIPLE_UNIQUE: return ;A @${error.item.key} entry is required, but none was found.
case Kind.REQUIRED_MISSING: return ;Unrecognized key: "${error.entry.key}".
case Kind.UNRECOGNIZED_KEY: return ;
default: throw new Error("Unknown metadata error.");
}
}
const result = validateAndStringify(metadata);
if (isRight(result)) {
console.log(result.Right.stringified);
result.Right.warnings.forEach(warning => {
console.warn(warning.summary);
console.warn(warning.description);
});
} else {
result.Left.forEach(error => {
console.error(stringifyError(error));
})
}
`
The code above will log the following:
``
// ==UserScript==
// @name Example Userscript
// @version 1.0.0
// @match ://example.com/
// @match ://www.example.com/
// @run-at document-start
// @noframes
// ==/UserScript==
Assuming the same definition of stringifyError as above, this is how metadata can be read from a userscript:
`typescript
import {
Kind, ValidationError, ReadFailure, ReadFailureType,
isRight, readAndValidate,
} from "userscript-metadata";
const userscript: string =
// ==UserScript==
// @name Example Userscript
// @version 1.0.0
// @match ://example.com/
// @match ://www.example.com/
// @run-at document-start
// @noframes
// ==/UserScript==
console.log("Hello world!");;
function stringifyFailure(failure: ReadFailure): string {
switch (failure.type) {
case ReadFailureType.EXTRACT: return Could not extract metadata block. Reason: ${failure.reason};Could not parse these lines in the metadata block:\n\n${failure.lines.join("\n")}
case ReadFailureType.PARSE: return ;Invalid metadata. Errors:\n\n${failure.errors.map(stringifyError).join("\n")}
case ReadFailureType.VALIDATE: return ;
default: throw new Error("Unknown metadata read failure.");
}
}
const result = readAndValidate(userscript);
if (isRight(result)) {
console.log(result.Right.metadata);
result.Right.warnings.forEach(warning => {
console.warn(warning.summary);
console.warn(warning.description);
});
} else {
console.error(stringifyFailure(result.Left));
}
`
The code above will log this:
`javascript`
{ name: 'Example Userscript',
version: '1.0.0',
match: [ '://example.com/', '://www.example.com/' ],
run_at: 'document-start',
noframes: true }
I.e. a value of type Metadata, identical to the one we gave as an argument to validateAndStringify before.
The demos above contain nothing that would yield any errors or warnings, but they contain code for handling them.
Try for example removing the @name entry to yield an error, or remove the @match entry to yield a warning.
You can customize metadata validation by using the more powerful higher-order functions validateAndStringifyWith and readAndValidateWith.validateAndStringify
If you call them with an options object, you get back customized versions of and readAndValidate, respectively:
`typescript
import {
StringItem, validateAndStringifyWith, DEFAULT_ITEMS, DEFAULT_WARNINGS,
} from "userscript-metadata";
const validateAndStringify_custom = validateAndStringifyWith({
items: {
...DEFAULT_ITEMS, // to keep default items
name: DEFAULT_ITEMS.name.butNotRequired(),
version: DEFAULT_ITEMS.version.withoutConstraints().butRequired(),
foo: new StringItem({
key: "foo",
required: false,
unique: true,
}),
useful: new BooleanItem({
key: "useful",
}),
},
warnings: DEFAULT_WARNINGS.concat([ // to keep default warnings
entries => (
!entries.some(entry => entry.key === "foo")
? [ {
summary: No @foo entry.,A @foo entry is recommended.
description: ,
} ]
: []
),
]),
underscoresAsHyphens: false,
});
const result = validateAndStringify_custom(metadata);
// ...
`
The example above demonstrates several customizations:
* The name item is not required anymore.version
* The item has been deprived of its default constraints and is now required.foo
* Two custom items, and useful, have been added.underscoresAsHyphens: false
* Another warning has been added to the default ones.
* , which means that a Metadata entry like run_at: "document-start" is interpreted as @run_at document-start and therefore invalid (@run-at being the actual key). With underscoresAsHyphens: true (default), translation between underscores and hyphens in keys is done automatically, so that the more convenient key run_at can be used in source code.
Both items and warnings are optional; if not specified, they default to DEFAULT_ITEMS and DEFAULT_WARNINGS, respectively.validateAndStringify
(In fact, is defined as validateAndStringifyWith()` in the actual code.)