0
# Instance Management
1

2
Core functionality for creating, configuring, and managing Yjs collaborative instances.
3

4
## Capabilities
5

6
### Y Constructor Function
7

8
Creates a new Yjs instance with specified configuration. This is the primary entry point for all Yjs functionality.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Yjs instance with specified configuration
13
 * @param {YjsOptions} options - Configuration object defining database, connector, and shared types
14
 * @returns {Promise<YjsInstance>} Promise resolving to configured Yjs instance
15
 */
16
function Y(options);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
// Basic setup with WebSocket connector
23
Y({
24
  db: { name: 'memory' },
25
  connector: { 
26
    name: 'websockets-client', 
27
    room: 'my-room',
28
    url: 'ws://localhost:1234'
29
  },
30
  share: { 
31
    document: 'Text',
32
    comments: 'Array'
33
  }
34
}).then(function (y) {
35
  // Use the instance
36
  console.log('Connected:', y.isConnected());
37
});
38

39
// WebRTC peer-to-peer setup
40
Y({
41
  db: { name: 'indexeddb' },
42
  connector: { 
43
    name: 'webrtc', 
44
    room: 'p2p-room'
45
  },
46
  share: { 
47
    canvas: 'Array',
48
    metadata: 'Map'
49
  }
50
}).then(function (y) {
51
  // Real-time drawing collaboration
52
  y.share.canvas.observe(function(event) {
53
    renderDrawing(event);
54
  });
55
});
56
```
57

58
### Instance Methods
59

60
#### isConnected
61

62
Checks the current connection status of the Yjs instance.
63

64
```javascript { .api }
65
/**
66
 * Check if the instance is currently connected to other peers
67
 * @returns {boolean} True if connected to at least one peer
68
 */
69
isConnected(): boolean;
70
```
71

72
#### disconnect
73

74
Temporarily disconnects from other instances while preserving local state.
75

76
```javascript { .api }
77
/**
78
 * Disconnect from other instances
79
 * Local data is preserved and will sync when reconnected
80
 */
81
disconnect(): void;
82
```
83

84
#### reconnect
85

86
Attempts to reconnect to other instances and sync changes.
87

88
```javascript { .api }
89
/**
90
 * Reconnect to other instances
91
 * Automatically syncs any changes made while disconnected
92
 */
93
reconnect(): void;
94
```
95

96
#### close
97

98
Closes the instance and cleans up resources while preserving data.
99

100
```javascript { .api }
101
/**
102
 * Close and cleanup the instance
103
 * Data is preserved in the database
104
 */
105
close(): void;
106
```
107

108
#### destroy
109

110
Completely destroys the instance and removes all associated data.
111

112
```javascript { .api }
113
/**
114
 * Destroy instance and remove all data
115
 * This action is irreversible
116
 */
117
destroy(): void;
118
```
119

120
### Extension System
121

122
#### Y.extend
123

124
Adds modules and extensions to the Yjs system before creating instances.
125

126
```javascript { .api }
127
/**
128
 * Add extensions/modules to Yjs
129
 * Must be called before creating instances that use the modules
130
 * @param {...any} modules - Modules to add (connectors, databases, types)
131
 */
132
Y.extend(...modules);
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
// Node.js - manually load required modules
139
Y.extend(
140
  require('y-memory'),
141
  require('y-array'),
142
  require('y-map'),
143
  require('y-websockets-client')
144
);
145

146
// Browser - modules auto-loaded from sourceDir
147
Y({
148
  sourceDir: '/bower_components',
149
  type: ['Array', 'Map', 'WebSocketsClient', 'Memory'],
150
  // ... rest of config
151
});
152
```
153

154
## Configuration Options
155

156
### Database Configuration
157

158
```javascript { .api }
159
interface DatabaseConfig {
160
  /** Database adapter name */
161
  name: 'memory' | 'indexeddb' | 'leveldb';
162
}
163
```
164

165
**Available database adapters:**
166
- `memory` - In-memory storage (data lost on page refresh)
167
- `indexeddb` - Browser persistent storage 
168
- `leveldb` - Node.js persistent storage
169

170
### Connector Configuration
171

172
```javascript { .api }
173
interface ConnectorConfig {
174
  /** Connector protocol name */
175
  name: 'webrtc' | 'websockets-client' | 'xmpp' | 'test';
176
  /** Room/channel identifier for sharing data */
177
  room: string;
178
  /** Connection endpoint URL (optional) */
179
  url?: string;
180
  /** Authentication information (optional) */
181
  auth?: any;
182
  /** Authentication validation function (optional) */
183
  checkAuth?: (auth: any) => boolean;
184
  /** Generate user ID locally (optional) */
185
  generateUserId?: boolean;
186
}
187
```
188

189
**Available connectors:**
190
- `webrtc` - Browser-to-browser peer-to-peer
191
- `websockets-client` - WebSocket client
192
- `xmpp` - XMPP multi-user chat rooms
193
- `test` - Testing connector for development
194

195
### Share Configuration
196

197
```javascript { .api }
198
interface ShareConfig {
199
  /** Map of shared object names to their types */
200
  [key: string]: 'Array' | 'Map' | 'Text' | 'Xml' | 'RichText';
201
}
202
```
203

204
### Module Loading Configuration
205

206
```javascript { .api }
207
interface ModuleConfig {
208
  /** Path to y-* modules (browser only) */
209
  sourceDir?: string;
210
  /** Array of modules to require (browser only) */
211
  type?: string[];
212
}
213
```
214

215
## Static Properties
216

217
### Y.debug
218

219
Debug logging utilities using the debug module.
220

221
```javascript { .api }
222
/**
223
 * Debug logging utilities
224
 * Browser: localStorage.debug = 'y*'
225
 * Node.js: DEBUG=y* node app.js
226
 */
227
Y.debug: DebugInterface;
228
```
229

230
### Y.utils
231

232
Utility functions and classes for extending Yjs.
233

234
```javascript { .api }
235
/**
236
 * Utility functions and classes namespace
237
 */
238
Y.utils: {
239
  EventListenerHandler: Function;
240
  EventHandler: Function;
241
  CustomType: Function;
242
  CustomTypeDefinition: Function;
243
  copyObject: Function;
244
  copyOperation: Function;
245
  compareIds: Function;
246
  generateGuid: Function;
247
};
248
```