@@ -346,160 +346,6 @@ It is recommended to set a default `user-agent` header for Node.js
346346applications. The default for the default Node.js document loader is
347347` jsonld.js ` .
348348
349- ### Events
350-
351- ** WARNING** : This feature is ** experimental** and the API, events, codes,
352- levels, and messages may change.
353-
354- Various events may occur during processing. The event handler system allows
355- callers to handle events as appropriate. Use cases can be as simple as logging
356- warnings, to displaying helpful UI hints, to failing on specific conditions.
357-
358- ** Note** : By default no event handler is used. This is due to general
359- performance considerations and the impossibility of providing a default handler
360- that would work for all use cases. Event construction and the handling system
361- are avoided by default providing the best performance for use cases where data
362- quality is known events are unnecessary.
363-
364- #### Event Structure
365-
366- Events are JSON objects with the following properties:
367-
368- - ** ` type ` ** : [ 'JsonLdEvent'] and optionally an array with others.
369- - ** ` code ` ** : A basic string code, similar to existing JSON-LD error codes.
370- - ** ` level ` ** : The severity level. Currently only ` warning ` is emitted.
371- - ** ` message ` ** : A human readable message describing the event.
372- - ** ` details ` ** : A JSON object with event specific details.
373-
374- #### Event Handlers
375-
376- Event handlers are chainable functions, arrays of handlers, objects mapping
377- codes to handlers, or any mix of these structures. Each function is passed an
378- object with two properties:
379-
380- - ** ` event ` ** : The event data.
381- - ** ` next ` ** : A function to call to an ` event ` and a ` next ` .
382-
383- The event handling system will process the handler structure, calling all
384- handlers, and continuing onto the next handler if ` next() ` is called. To stop
385- processing, throw an error, or return without calling ` next() ` .
386-
387- This design allows for composable handler structures, for instance to handle
388- some conditions with a custom handler, and default to generic "unknown event"
389- or logging handler.
390-
391- ** Note** : Handlers are currently synchronous due to possible performance
392- issues. This may change to an ` async ` /` await ` design in the future.
393-
394- ``` js
395- // expand a document with a logging event handler
396- const expanded = await jsonld .expand (data, {
397- // simple logging handler
398- eventHandler : function ({event , next}) {
399- console .log (' event' event });
400- }
401- });
402- ```
403-
404- ``` js
405- function logEventHandler ({event , next}) {
406- console .log (' event' event });
407- next ();
408- }
409-
410- function noWarningsEventHandler ({event , next}) {
411- if (event .level === ' warning'
412- throw new Error (' No warnings!' event });
413- }
414- next ();
415- }
416-
417- function unknownEventHandler ({event , next}) {
418- throw new Error (' Unknown event' event });
419- }
420-
421- // expand a document with an array of event handlers
422- const expanded = await jsonld .expand (data, {
423- // array of handlers
424- eventHandler: [
425- logEventHandler,
426- noWarningsEventHandler,
427- unknownEventHandler
428- ]}
429- });
430- ```
431-
432- ``` js
433- const handler = {
434- ' a mild event code ' : function ({event }) {
435- console .log (' the thing happened' event });
436- },
437- ' a serious event code ' : function ({event }) {
438- throw new Error (' the specific thing happened' event });
439- }
440- };
441- // expand a document with a code map event handler
442- const expanded = await jsonld .expand (data, {eventHandler});
443- ```
444-
445- #### Safe Validation
446-
447- A common use case is to avoid JSON-LD constructs that will result in lossy
448- behavior. The JSON-LD specifications have notes about when data is dropped.
449- This can be especially important when calling [ ` canonize ` ] [ ] in order to
450- digitally sign data. The event system can be used to detect and avoid these
451- situations. A special "safe mode" is available that will inject an initial
452- event handler that fails on conditions that would result in data loss. More
453- benign events may fall back to the passed event handler, if any.
454-
455- ** Note** : This mode is designed to be the common way that digital signing and
456- similar applications use this library.
457-
458- The ` safe ` options flag set to ` true ` enables this behavior:
459-
460- ``` js
461- // expand a document in safe mode
462- const expanded = await jsonld .expand (data, {safe: true });
463- ```
464-
465- ``` js
466- // expand a document in safe mode, with fallback handler
467- const expanded = await jsonld .expand (data, {
468- safe: true
469- eventHandler : function ({event }) { /* ... */
470- });
471- ```
472-
473- #### Available Handlers
474-
475- Some predefined event handlers are available to use alone or as part of a more
476- complex handler:
477-
478- - ** safeEventHandler** : The handler used when ` safe ` is ` true ` .
479- - ** logEventHandler** : A debugging handler that outputs to the console.
480- - ** logWarningHandler** : A debugging handler that outputs ` warning ` level
481- events to the console.
482- - ** unhandledEventHandler** : Throws on all events not yet handled.
483-
484- #### Default Event Handler
485-
486- A default event handler can be set. It will be the only handler when not in
487- safe mode, and the second handler when in safe mode.
488-
489- ``` js
490- // fail on unknown events
491- jsonld .setDefaultEventHandler (jsonld .unhandledEventHandler );
492- // will use unhandled event handler by default
493- const expanded = await jsonld .expand (data);
494- ```
495-
496- ``` js
497- // always use safe mode event handler, ignore other events
498- jsonld .setDefaultEventHandler (jsonld .safeEventHandler );
499- // will use safe mode handler, like `{safe: true}`
500- const expanded = await jsonld .expand (data);
501- ```
502-
503349Related Modules
504350---------------
505351
0 commit comments