createFrom added to guide (#1423)

* createFrom added to guide

* clearer variable names

* simplifying example

* update comment

* Update site/testsuites/testsuite-javascript/__tests__/web5/build/decentralized-web-nodes/write-to-dwn.test.js

Co-authored-by: Angie Jones <[email protected]>

---------

Co-authored-by: Angie Jones <[email protected]>

site/docs/web5/build/decentralized-web-nodes/write-to-dwn.mdx

@@ -9,24 +9,28 @@ Various data types, such as text, JSON, images, streams or files, can be stored
 
 ### Create a text record
 
-<CodeSnippet functionName='createTextRecord'/>
+<CodeSnippet snippetName='createTextRecord'/>
 
 ### Create a JSON record
 
-<CodeSnippet functionName='createJsonRecord'/>
+<CodeSnippet snippetName='createJsonRecord'/>
 
 ### Create a blob or image record
 
-<CodeSnippet functionName='uploadImage'/>
+<CodeSnippet snippetName='uploadImage'/>
 
 ### Create a file record
 
-<CodeSnippet functionName='uploadFile'/>
+<CodeSnippet snippetName='uploadFile'/>
 
 ### Create records with mixed data
 You can also store mixed data via JSON - including text, images, or files.
 
-<CodeSnippet functionName='createMixedRecord'/>
+<CodeSnippet snippetName='createMixedRecord'/>
 
+## Create records from an existing record
+You can create a new version of a record while maintaining a link to the version of the original record.
+
+<CodeSnippet snippetName='createRecordFrom'/>
 
 For more information on writing records to DWNs, see our [API Guide](https://tbd54566975.github.io/web5-js/classes/_web5_api.DwnApi.html#records).

site/testsuites/testsuite-javascript/__tests__/web5/build/decentralized-web-nodes/write-to-dwn.test.js

@@ -21,12 +21,34 @@ describe('write-to-dwn', () => {
  });
 
  test('createTextRecord creates a text record', async () => {
- const record = await createTextRecord(web5);
+ // :snippet-start: createTextRecord
+ // Create a plain text record
+ const { record } = await web5.dwn.records.create({
+ data: {
+ content: "Hello Web5",
+ description: "Keep Building!"
+ },
+ message: {
+ dataFormat: 'application/json'
+ }
+ });
+ // :snippet-end:
  expect(record).toBeDefined();
  });
 
  test('createJsonRecord creates a JSON record', async () => {
- const record = await createJsonRecord(web5);
+ // :snippet-start: createJsonRecord
+ // Create a JSON record
+ const { record } = await web5.dwn.records.create({
+ data: {
+ content: "Hello Web5",
+ description: "Keep Building!"
+ },
+ message: {
+ dataFormat: 'application/json'
+ }
+ });
+ // :snippet-end:
  expect(record).toBeDefined();
  });
 
@@ -36,8 +58,20 @@ describe('write-to-dwn', () => {
  files: [new Blob(['fake image data'], { type: 'image/png' })],
  },
  };
-
- const record = await uploadImage(mockEvent);
+ // :snippet-start: uploadImage
+ // Create a blob record
+ async function upload(event) {
+ const blob = new Blob(event.currentTarget.files, { type: "image/png" });
+ const { record } = await web5.dwn.records.create({
+ data: blob,
+ message: {
+ dataFormat: "image/png"
+ }
+ });
+ return record;
+ }
+ //:snippet-end:
+ const record = await upload(mockEvent);
  expect(record).toBeDefined();
  });
 
@@ -49,16 +83,83 @@ describe('write-to-dwn', () => {
  ],
  },
  };
+ // :snippet-start: uploadFile
+ // Create a file record
+ async function upload(event) {
+ const file = event.currentTarget.files[0];
+ const { status: fileStatus, record } = await web5.dwn.records.create({
+ data: file,
+ message: {
+ schema: "https://schema.org/path/to/schema",
+ dataFormat: "application/octet-stream"
+ }
+ });
+ return record;
+ }
+ //:snippet-end:
 
- const record = await uploadFile(mockEvent);
+ const record = await upload(mockEvent);
  expect(record).toBeDefined();
  });
  test('createMixedRecord creates a message with an image and file', async () => {
  const username = 'testUser';
  const messageText = 'testMessage';
  const imageFile = new Blob(['fake image data'], { type: 'image/png' });
+ // :snippet-start: createMixedRecord
+ // Create a mixed record
+ async function createMessage(username, messageText, imageFile) {
+ let base64Image = null;
+
+ if (imageFile) {
+ const binaryImage = await imageFile.arrayBuffer();
+ base64Image = btoa(
+ new Uint8Array(binaryImage).reduce(
+ (data, byte) => data + String.fromCharCode(byte),
+ ""
+ )
+ );
+ }
+
+ const messageData = {
+ username,
+ message: messageText,
+ image: base64Image
+ };
 
- const record = await createMixedRecord(username, messageText, imageFile);
+ const { record } = await web5.dwn.records.create({
+ data: messageData,
+ message: {
+ schema: "http://schema-registry.org/message",
+ dataFormat: "application/json"
+ },
+ });
+ return record;
+ }
+ //:snippet-end:
+
+ const record = await createMessage(username, messageText, imageFile);
  expect(record).toBeDefined();
  });
 });
+
+test('createRecordFrom creates a record from an existing record', async () => {
+ const { record: originalRecord } = await web5.dwn.records.create({
+ data: 'Hello, Web5!',
+ message: {
+ dataFormat: 'text/plain',
+ },
+ });
+ // :snippet-start: createRecordFrom
+ // Create a new version of the record based on the original record
+ const { record: newVersionRecord } = await web5.dwn.records.createFrom({
+ record: originalRecord,
+ data: 'I am a new version of the original record!',
+ message: {
+ dataFormat: 'text/plain',
+ published: true,
+ },
+ });
+ // :snippet-end:
+ const newRecordDataText = await newVersionRecord.data.text();
+ expect(newRecordDataText).toBe('I am a new version of the original record!');
+});