Delta
Simple and expressive JSON format for describing rich-text content and their changes
Install / Use
/learn @slab/DeltaREADME
Delta 
Deltas are a simple, yet expressive format that can be used to describe contents and changes. The format is JSON based, and is human readable, yet easily parsible by machines. Deltas can describe any rich text document, includes all text and formatting information, without the ambiguity and complexity of HTML.
A Delta is made up of an Array of Operations, which describe changes to a document. They can be an insert, delete or retain. Note operations do not take an index. They always describe the change at the current index. Use retains to "keep" or "skip" certain parts of the document.
Don’t be confused by its name Delta—Deltas represents both documents and changes to documents. If you think of Deltas as the instructions from going from one document to another, the way Deltas represent a document is by expressing the instructions starting from an empty document.
Quick Example
// Document with text "Gandalf the Grey"
// with "Gandalf" bolded, and "Grey" in grey
const delta = new Delta([
{ insert: 'Gandalf', attributes: { bold: true } },
{ insert: ' the ' },
{ insert: 'Grey', attributes: { color: '#ccc' } }
]);
// Change intended to be applied to above:
// Keep the first 12 characters, insert a white 'White'
// and delete the next four characters ('Grey')
const death = new Delta().retain(12)
.insert('White', { color: '#fff' })
.delete(4);
// {
// ops: [
// { retain: 12 },
// { insert: 'White', attributes: { color: '#fff' } },
// { delete: 4 }
// ]
// }
// Applying the above:
const restored = delta.compose(death);
// {
// ops: [
// { insert: 'Gandalf', attributes: { bold: true } },
// { insert: ' the ' },
// { insert: 'White', attributes: { color: '#fff' } }
// ]
// }
This README describes Deltas in its general form and API functionality. Additional information on the way Quill specifically uses Deltas can be found on its own Delta docs. A walkthough of the motivation and design thinking behind Deltas are on Designing the Delta Format.
This format is suitable for Operational Transform and defines several functions to support this use case.
Contents
Operations
Construction
Documents
These methods called on or with non-document Deltas will result in undefined behavior.
Utility
Operational Transform
Operations
Insert Operation
Insert operations have an insert key defined. A String value represents inserting text. Any other type represents inserting an embed (however only one level of object comparison will be performed for equality).
In both cases of text and embeds, an optional attributes key can be defined with an Object to describe additonal formatting information. Formats can be changed by the retain operation.
// Insert a bolded "Text"
{ insert: "Text", attributes: { bold: true } }
// Insert a link
{ insert: "Google", attributes: { link: 'https://www.google.com' } }
// Insert an embed
{
insert: { image: 'https://octodex.github.com/images/labtocat.png' },
attributes: { alt: "Lab Octocat" }
}
// Insert another embed
{
insert: { video: 'https://www.youtube.com/watch?v=dMH0bHeiRNg' },
attributes: {
width: 420,
height: 315
}
}
Delete Operation
Delete operations have a Number delete key defined representing the number of characters to delete. All embeds have a length of 1.
// Delete the next 10 characters
{ delete: 10 }
Retain Operation
Retain operations have a Number retain key defined representing the number of characters to keep (other libraries might use the name keep or skip). An optional attributes key can be defined with an Object to describe formatting changes to the character range. A value of null in the attributes Object represents removal of that key.
Note: It is not necessary to retain the last characters of a document as this is implied.
// Keep the next 5 characters
{ retain: 5 }
// Keep and bold the next 5 characters
{ retain: 5, attributes: { bold: true } }
// Keep and unbold the next 5 characters
// More specifically, remove the bold key in the attributes Object
// in the next 5 characters
{ retain: 5, attributes: { bold: null } }
Construction
constructor
Creates a new Delta object.
Methods
new Delta()new Delta(ops)new Delta(delta)
Parameters
ops- Array of operationsdelta- Object with anopskey set to an array of operations
Note: No validity/sanity check is performed when constructed with ops or delta. The new delta's internal ops array will also be assigned from ops or delta.ops without deep copying.
Example
const delta = new Delta([
{ insert: 'Hello World' },
{ insert: '!', attributes: { bold: true }}
]);
const packet = JSON.stringify(delta);
const other = new Delta(JSON.parse(packet));
const chained = new Delta().insert('Hello World').insert('!', { bold: true });
insert()
Appends an insert operation. Returns this for chainability.
Methods
insert(text, attributes)insert(embed, attributes)
Parameters
text- String representing text to insertembed- Object representing embed type to insertattributes- Optional attributes to apply
Example
delta.insert('Text', { bold: true, color: '#ccc' });
delta.insert({ image: 'https://octodex.github.com/images/labtocat.png' });
delete()
Appends a delete operation. Returns this for chainability.
Methods
delete(length)
Parameters
length- Number of characters to delete
Example
delta.delete(5);
retain()
Appends a retain operation. Returns this for chainability.
Methods
retain(length, attributes)
Parameters
length- Number of characters to retainattributes- Optional attributes to apply
Example
delta.retain(4).retain(5, { color: '#0c6' });
Documents
concat()
Returns a new Delta representing the concatenation of this and another document Delta's operations.
Methods
concat(other)
Parameters
other- Document Delta to concatenate
Returns
Delta- Concatenated document Delta
Example
const a = new Delta().insert('Hello');
const b = new Delta().insert('!', { bold: true });
// {
// ops: [
// { insert: 'Hello' },
// { insert: '!', attributes: { bold: true } }
// ]
// }
const concat = a.concat(b);
diff()
Returns a Delta representing the difference between two documents. Optionally, accepts a suggested index where change took place, often representing a cursor position before change.
Methods
diff(other)diff(other, index)
Parameters
other- Document Delta to diff againstindex- Suggested index where change took place
Returns
Delta- difference between the two documents
Example
const a = new Delta().insert('Hello');
const b = new Delta().insert('Hello!');
const diff = a.diff(b); // { ops: [{ retain: 5 }, { insert: '!' }] }
// a.compose(diff) == b
eachLine()
Iterates through document Delta, calling a given function with a Delta and attributes object, representing the line segment.
Methods
eachLine(predicate, newline)
Parameters
predicate- function to call on each line groupnewline- newline character, defaults to\n
Example
const delta = new Delta().insert('Hello\n\n')
.insert('World')
.insert({ image: 'octocat.png' })
.insert('\n', { align: 'right' })
.insert('!');
delta.eachLine((line, attributes, i) => {
console.log(line, attributes, i);
// Can return false to exit loop early
});
// Should log:
// { ops: [{ insert: 'Hello' }] }, {}, 0
// { ops: [] }, {}, 1
// { ops: [{ insert: 'World' }, { insert: { image: 'octocat.png' } }] }, { align: 'right' }, 2
// { ops: [{ insert: '!' }] }, {}, 3
invert()
Returned an inverted delta that has the opposite effect of against a base document delta. That is base.compose(delta).compose(inverted) === base.
Methods
invert(base)
Parameters
base- Document delta to invert against
Returns
Delta- inverted delta against the base delta
Example
const base = new Delta().insert('Hello\n')
.insert('World');
const delta = new Delta().retain(6, { bold: true }).insert('!').delete(5);
const inverted = delta.invert(base); // { ops: [
// { retain: 6, attributes: { bold: null } },
// { insert: 'World' },
// { delete:
