0
# MIME Data Management
1

2
Storage and management system for arbitrary data organized by MIME types. Designed for transferring arbitrary data and objects within the same application without enforcing MIME type "correctness".
3

4
## Capabilities
5

6
### MimeData Class
7

8
A class that stores data organized by MIME types, allowing applications to store and retrieve arbitrary data with type labels.
9

10
```typescript { .api }
11
/**
12
 * An object which stores MIME data for general application use.
13
 * 
14
 * Notes:
15
 * This class does not attempt to enforce "correctness" of MIME types
16
 * and their associated data. Since this class is designed to transfer
17
 * arbitrary data and objects within the same application, it assumes
18
 * that the user provides correct and accurate data.
19
 */
20
class MimeData {
21
  /**
22
   * Get an array of the MIME types contained within the dataset
23
   * @returns A new array of the MIME types, in order of insertion
24
   */
25
  types(): string[];
26

27
  /**
28
   * Test whether the dataset has an entry for the given type
29
   * @param mime - The MIME type of interest
30
   * @returns true if the dataset contains a value for the given MIME type, false otherwise
31
   */
32
  hasData(mime: string): boolean;
33

34
  /**
35
   * Get the data value for the given MIME type
36
   * @param mime - The MIME type of interest
37
   * @returns The value for the given MIME type, or undefined if the dataset does not contain a value for the type
38
   */
39
  getData(mime: string): any | undefined;
40

41
  /**
42
   * Set the data value for the given MIME type
43
   * @param mime - The MIME type of interest
44
   * @param data - The data value for the given MIME type
45
   * 
46
   * Notes:
47
   * This will overwrite any previous entry for the MIME type
48
   */
49
  setData(mime: string, data: any): void;
50

51
  /**
52
   * Remove the data entry for the given MIME type
53
   * @param mime - The MIME type of interest
54
   * 
55
   * Notes:
56
   * This is a no-op if there is no entry for the given MIME type
57
   */
58
  clearData(mime: string): void;
59

60
  /**
61
   * Remove all data entries from the dataset
62
   */
63
  clear(): void;
64
}
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
import { MimeData } from "@lumino/coreutils";
71

72
// Create a new MIME data container
73
const mimeData = new MimeData();
74

75
// Store different types of data
76
mimeData.setData("text/plain", "Hello, World!");
77
mimeData.setData("application/json", JSON.stringify({ name: "Alice", age: 30 }));
78
mimeData.setData("text/html", "<p>Hello, <strong>World!</strong></p>");
79
mimeData.setData("application/x-custom", { custom: "data", array: [1, 2, 3] });
80

81
// Check what MIME types are available
82
const types = mimeData.types();
83
console.log(types); // ["text/plain", "application/json", "text/html", "application/x-custom"]
84

85
// Check if specific data exists
86
const hasText = mimeData.hasData("text/plain"); // true
87
const hasImage = mimeData.hasData("image/png"); // false
88

89
// Retrieve data
90
const plainText = mimeData.getData("text/plain"); // "Hello, World!"
91
const jsonData = mimeData.getData("application/json"); // '{"name":"Alice","age":30}'
92
const missingData = mimeData.getData("missing/type"); // undefined
93

94
// Parse retrieved JSON data
95
const parsedData = JSON.parse(jsonData);
96
console.log(parsedData.name); // "Alice"
97

98
// Update existing data (overwrites previous entry)
99
mimeData.setData("text/plain", "Updated text content");
100

101
// Remove specific data
102
mimeData.clearData("text/html");
103
console.log(mimeData.hasData("text/html")); // false
104

105
// Clear all data
106
mimeData.clear();
107
console.log(mimeData.types()); // []
108
```
109

110
### Common Use Cases
111

112
**Drag and Drop Operations:**
113

114
```typescript
115
import { MimeData } from "@lumino/coreutils";
116

117
// Create data for drag and drop
118
const dragData = new MimeData();
119
dragData.setData("text/plain", "Draggable text");
120
dragData.setData("text/uri-list", "https://example.com");
121
dragData.setData("application/x-custom-widget", { widgetId: "widget-123", config: {} });
122

123
// In drop handler, check available formats
124
if (dragData.hasData("application/x-custom-widget")) {
125
  const widgetData = dragData.getData("application/x-custom-widget");
126
  // Handle custom widget drop
127
} else if (dragData.hasData("text/uri-list")) {
128
  const url = dragData.getData("text/uri-list");
129
  // Handle URL drop
130
} else if (dragData.hasData("text/plain")) {
131
  const text = dragData.getData("text/plain");
132
  // Handle text drop
133
}
134
```
135

136
**Clipboard Operations:**
137

138
```typescript
139
import { MimeData } from "@lumino/coreutils";
140

141
// Prepare clipboard data with multiple formats
142
const clipboardData = new MimeData();
143
clipboardData.setData("text/plain", "Plain text version");
144
clipboardData.setData("text/html", "<b>Rich text version</b>");
145
clipboardData.setData("application/json", JSON.stringify({ id: 1, title: "Item" }));
146

147
// Application can choose the best available format
148
const availableTypes = clipboardData.types();
149
if (availableTypes.includes("application/json")) {
150
  const jsonData = JSON.parse(clipboardData.getData("application/json"));
151
  // Use structured data
152
} else if (availableTypes.includes("text/html")) {
153
  const htmlData = clipboardData.getData("text/html");
154
  // Use rich text
155
} else {
156
  const plainData = clipboardData.getData("text/plain");
157
  // Fallback to plain text
158
}
159
```
160

161
**Inter-Component Data Transfer:**
162

163
```typescript
164
import { MimeData } from "@lumino/coreutils";
165

166
// Transfer complex data between application components
167
const transferData = new MimeData();
168
transferData.setData("application/x-user-profile", {
169
  id: 123,
170
  name: "Alice Smith",
171
  preferences: { theme: "dark", language: "en" }
172
});
173
transferData.setData("text/csv", "id,name,theme\n123,Alice Smith,dark");
174
transferData.setData("text/plain", "Alice Smith (ID: 123)");
175

176
// Receiving component can choose appropriate format
177
function handleData(data: MimeData) {
178
  if (data.hasData("application/x-user-profile")) {
179
    // Use rich object data
180
    const profile = data.getData("application/x-user-profile");
181
    return profile;
182
  } else if (data.hasData("text/csv")) {
183
    // Parse CSV data
184
    const csv = data.getData("text/csv");
185
    return parseCsv(csv);
186
  } else {
187
    // Fallback to plain text
188
    return { name: data.getData("text/plain") };
189
  }
190
}
191
```