0
# Mongoskin
1

2
Mongoskin is a JavaScript wrapper library that provides a simplified and enhanced API layer on top of the official MongoDB Node.js driver (node-mongodb-native). It offers callback-based operations with lazy connection handling, convenient helper methods, and streamlined connection management to reduce boilerplate code while maintaining compatibility with the underlying MongoDB driver's API.
3

4
## Package Information
5

6
- **Package Name**: mongoskin
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mongoskin`
10

11
## Core Imports
12

13
```javascript
14
const mongoskin = require('mongoskin');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const mongoskin = require('mongoskin');
21

22
// Connect to database using connection string
23
const db = mongoskin.db('mongodb://localhost:27017/myapp');
24

25
// Bind collections for easy access
26
db.bind('users');
27
db.bind('posts');
28

29
// Use enhanced collection methods
30
db.users.findById('507f1f77bcf86cd799439011', (err, user) => {
31
  if (err) throw err;
32
  console.log(user);
33
});
34

35
// Insert and find with simplified API
36
db.posts.insert({ title: 'Hello World', author: 'Alice' }, (err, result) => {
37
  if (err) throw err;
38
  
39
  db.posts.findItems({ author: 'Alice' }, (err, posts) => {
40
    if (err) throw err;
41
    console.log(posts);
42
    db.close();
43
  });
44
});
45
```
46

47
## Architecture
48

49
Mongoskin implements a "Skin" class pattern where each MongoDB native class gets a corresponding wrapper:
50

51
- **Lazy Connection Pattern**: Methods can be called before connection is established; connection opens automatically when needed
52
- **State Management**: Tracks connection state (CLOSE, OPENING, OPEN) for efficient resource management  
53
- **API Compatibility**: All native MongoDB driver methods are proxied through to underlying instances
54
- **Enhanced Methods**: Additional convenience methods layered on top of standard MongoDB API
55
- **Event-driven**: Uses EventEmitter pattern for connection lifecycle management
56

57
## Capabilities
58

59
### Database Connection
60

61
Core database connection functionality with lazy connection management and enhanced connection methods.
62

63
```javascript { .api }
64
function db(connectionString, options): SkinDb;
65

66
class MongoClient {
67
  static connect(connectionString, options, callback): SkinDb;
68
}
69
```
70

71
[Database Connection](./database-connection.md)
72

73
### Collection Operations
74

75
Enhanced collection interface with convenience methods for common database operations, including findById, updateById, and removeById.
76

77
```javascript { .api }
78
class Collection {
79
  find(query, options, callback): SkinCursor;
80
  findItems(query, options, callback): Collection;
81
  findEach(query, options, eachCallback): Collection;
82
  findById(id, callback): Collection;
83
  updateById(id, doc, callback): Collection;
84
  removeById(id, callback): Collection;
85
  bind(extendObject): void;
86
}
87
```
88

89
[Collection Operations](./collection-operations.md)
90

91
### Query and Cursor Management
92

93
Cursor operations for iterating through query results with automatic connection handling.
94

95
```javascript { .api }
96
class Cursor {
97
  toArray(callback): void;
98
  each(callback): void;
99
  next(callback): void;
100
  limit(limit): Cursor;
101
  skip(skip): Cursor;
102
  sort(sort): Cursor;
103
}
104
```
105

106
[Query and Cursor Management](./query-cursor.md)
107

108
### Administrative Operations
109

110
Database administration capabilities including user management, indexing, and server statistics.
111

112
```javascript { .api }
113
class Admin {
114
  listDatabases(callback): void;
115
  serverStatus(callback): void;
116
  addUser(username, password, options, callback): void;
117
  removeUser(username, callback): void;
118
}
119
```
120

121
[Administrative Operations](./admin-operations.md)
122

123
### GridFS File Storage
124

125
GridFS operations for storing and retrieving large files in MongoDB with streaming support.
126

127
```javascript { .api }
128
class GridStore {
129
  static exist(db, name, callback): void;
130
  static list(db, callback): void;
131
  static read(db, name, callback): void;
132
  static readlines(db, name, callback): void;
133
  static unlink(db, name, callback): void;
134
  open(mode, callback): void;
135
  write(data, callback): void;
136
  close(callback): void;
137
}
138
```
139

140
[GridFS File Storage](./gridfs-storage.md)
141

142
### Utilities and Helpers
143

144
Helper functions for common MongoDB operations including ObjectID conversion and validation.
145

146
```javascript { .api }
147
const helper = {
148
  toObjectID(hex): ObjectID;
149
  isObjectID(idstr): boolean;
150
};
151

152
const utils = {
153
  makeSkinClass(NativeClass, useNativeConstructor): Function;
154
};
155
```
156

157
[Utilities and Helpers](./utilities-helpers.md)
158

159
## Types
160

161
```javascript { .api }
162
// Core wrapper classes
163
class SkinDb extends Db {
164
  collection(name, options): SkinCollection;
165
  bind(name, options): SkinCollection;
166
  admin(): SkinAdmin;
167
  gridStore(...args): SkinGridStore;
168
  open(callback): SkinDb;
169
  close(callback): SkinDb;
170
  isOpen(): boolean;
171
}
172

173
class SkinCollection extends Collection {
174
  bind(extendObject): void;
175
  findItems(query, options, callback): SkinCollection;
176
  findEach(query, options, eachCallback): SkinCollection;
177
  findById(id, callback): SkinCollection;
178
  updateById(id, doc, callback): SkinCollection;
179
  removeById(id, callback): SkinCollection;
180
}
181

182
class SkinCursor extends Cursor {
183
  // All standard cursor methods plus lazy connection handling
184
}
185

186
class SkinAdmin extends Admin {
187
  // All standard admin methods with enhanced connection handling
188
}
189

190
class SkinGridStore extends GridStore {
191
  // All standard GridStore methods with lazy connection
192
}
193

194
// Connection states
195
const STATE_CLOSE = 0;
196
const STATE_OPENNING = 1; 
197
const STATE_OPEN = 2;
198

199
// Default port constant
200
const DEFAULT_PORT = 27017;
201

202
// MongoDB native types (re-exported)
203
class ObjectID {
204
  constructor(id): ObjectID;
205
  toString(): string;
206
  static createFromHexString(hex): ObjectID;
207
  static isValid(id): boolean;
208
}
209
```