Field Logging
Joist provides field logging to visualize when/why fields are being set on entities.
Usage
Field logging is currently enabled on an individual EntityManager
instance:
// Logs all field sets on this EntityManager
em.setFieldLogging(true);
This will produce console output like:
a#1.firstName = a1 at newAuthor.ts:13
a#1.age = 40 at newAuthor.ts:13
b#1.title = title at newBook.ts:9
b#1.order = 1 at newBook.ts:9
b#1.author = Author#1 at newBook.ts:9
b#1.notes = Notes for title at defaults.ts:28
Where a#1
is the tagged id of a new/unsaved Author
instance, and b#
is the tagged id of a new/unsaved Book
instance.
The at (file):(line)
, which should help track down which hook or method is setting the field.
The code that determines the correct at (file):(line)
to output is currently a heuristic; if you see incorrect or missing file/line information, please file an issue. Thank you!
Filtering Shorthand
If you want to quickly setup field logging, we support a string "spec" shorthand:
// Single entity, multiple fields
em.setFieldLogging("Author.firstName,lastName");
// Multiple entities, breakpoints enabled
em.setFieldLogging(["Author.lastName", "Book.title!"]);
Filtering by Entity & Fields
If you want to log only sets for a specific entity, or certain fields, you can pass a watches
argument to the FieldLogger
constructor:
em.setFieldLogging(new FieldLogger([
// Log all field sets for Authors
{ entity: "Author" },
// Log only title changes to Books
{ entity: "Book", fieldNames: ["title"] },
]));
Enabling Breakpoints
If you're running in debug mode, you can tell Joist to trigger a breakpoint on the field set:
// Use a ! shorthand in the spec string
em.setFieldLogging("Author.firstName!");
// Or pass `breakpoint: true` to the FieldLogger constructor
em.setFieldLogging(new FieldLogger(
[{ entity: "Author", fieldNames: ["firstName"], breakpoint: true }],
));
And your debugger will stop anytime the firstName
field is mutated.
This can be extremely useful for finding "who" is setting/changing a field in more complex/multi-step scenarios.
Colorized Output
Currently, the FieldLogger
always output colorized output, similar to Joist's other logging output.
This makes for the best experience with running/debugging tests, like in Jest, which is currently the primary use case for Joist's logging.