@simplysm/storage 14.0.1 → 14.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# @simplysm/storage
|
|
2
|
+
|
|
3
|
+
Storage client library for FTP, FTPS, and SFTP file operations.
|
|
4
|
+
|
|
5
|
+
Platform: Node.js.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @simplysm/storage
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## API Overview
|
|
14
|
+
|
|
15
|
+
### Types
|
|
16
|
+
|
|
17
|
+
#### StorageConnConfig
|
|
18
|
+
|
|
19
|
+
Connection configuration for storage clients.
|
|
20
|
+
|
|
21
|
+
| Field | Type | Description |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `host` | `string` | Server hostname or IP address |
|
|
24
|
+
| `port?` | `number` | Server port (protocol default if omitted) |
|
|
25
|
+
| `user?` | `string` | Username |
|
|
26
|
+
| `password?` | `string` | Password |
|
|
27
|
+
|
|
28
|
+
#### FileInfo
|
|
29
|
+
|
|
30
|
+
File/directory entry returned by `list()`.
|
|
31
|
+
|
|
32
|
+
| Field | Type | Description |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| `name` | `string` | File or directory name |
|
|
35
|
+
| `isFile` | `boolean` | `true` if this entry is a file, `false` if it is a directory |
|
|
36
|
+
|
|
37
|
+
#### StorageProtocol
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
type StorageProtocol = "ftp" | "ftps" | "sftp";
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
#### StorageClient (interface)
|
|
44
|
+
|
|
45
|
+
Common interface implemented by all storage clients.
|
|
46
|
+
|
|
47
|
+
| Method | Signature | Description |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `connect` | `(config: StorageConnConfig) => Promise<void>` | Connect to the server |
|
|
50
|
+
| `mkdir` | `(dirPath: string) => Promise<void>` | Create directory (recursive) |
|
|
51
|
+
| `rename` | `(fromPath: string, toPath: string) => Promise<void>` | Rename a file or directory |
|
|
52
|
+
| `list` | `(dirPath: string) => Promise<FileInfo[]>` | List directory contents |
|
|
53
|
+
| `readFile` | `(filePath: string) => Promise<Bytes>` | Read file contents |
|
|
54
|
+
| `exists` | `(filePath: string) => Promise<boolean>` | Check if file or directory exists |
|
|
55
|
+
| `put` | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | Upload a local file path or byte data to remote path |
|
|
56
|
+
| `uploadDir` | `(fromPath: string, toPath: string) => Promise<void>` | Upload entire local directory to remote path |
|
|
57
|
+
| `remove` | `(filePath: string) => Promise<void>` | Remove a file |
|
|
58
|
+
| `close` | `() => Promise<void>` | Close the connection. Safe to call multiple times. |
|
|
59
|
+
|
|
60
|
+
### Clients
|
|
61
|
+
|
|
62
|
+
#### FtpStorageClient
|
|
63
|
+
|
|
64
|
+
FTP/FTPS client. Implements `StorageClient`. Uses `basic-ftp` internally.
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
constructor(secure?: boolean)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
| Parameter | Type | Default | Description |
|
|
71
|
+
|---|---|---|---|
|
|
72
|
+
| `secure` | `boolean` | `false` | Set `true` for FTPS |
|
|
73
|
+
|
|
74
|
+
All methods from `StorageClient` are implemented. Prefer using `StorageFactory.connect` over direct instantiation.
|
|
75
|
+
|
|
76
|
+
#### SftpStorageClient
|
|
77
|
+
|
|
78
|
+
SFTP client. Implements `StorageClient`. Uses `ssh2-sftp-client` internally.
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
constructor()
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Authentication priority when `password` is not provided:
|
|
85
|
+
1. SSH private key (`~/.ssh/id_ed25519`) + SSH agent
|
|
86
|
+
2. SSH agent only (fallback when key parsing fails)
|
|
87
|
+
|
|
88
|
+
All methods from `StorageClient` are implemented. Prefer using `StorageFactory.connect` over direct instantiation.
|
|
89
|
+
|
|
90
|
+
### Factory
|
|
91
|
+
|
|
92
|
+
#### StorageFactory
|
|
93
|
+
|
|
94
|
+
Static factory class for creating and managing storage connections.
|
|
95
|
+
|
|
96
|
+
##### Static Methods
|
|
97
|
+
|
|
98
|
+
| Method | Signature | Description |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `connect` | `<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R \| Promise<R>) => Promise<R>` | Connect to storage, execute callback, and automatically close the connection. The connection is closed even if the callback throws. |
|
|
101
|
+
|
|
102
|
+
## Usage
|
|
103
|
+
|
|
104
|
+
### Recommended: StorageFactory (auto-managed connection)
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
import { StorageFactory } from "@simplysm/storage";
|
|
108
|
+
|
|
109
|
+
const files = await StorageFactory.connect("sftp", {
|
|
110
|
+
host: "example.com",
|
|
111
|
+
user: "deploy",
|
|
112
|
+
}, async (client) => {
|
|
113
|
+
await client.mkdir("/remote/path");
|
|
114
|
+
await client.put("/local/file.txt", "/remote/file.txt");
|
|
115
|
+
return client.list("/remote/path");
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Direct client usage
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
import { SftpStorageClient } from "@simplysm/storage";
|
|
123
|
+
|
|
124
|
+
const client = new SftpStorageClient();
|
|
125
|
+
await client.connect({ host: "example.com", user: "deploy" });
|
|
126
|
+
try {
|
|
127
|
+
const exists = await client.exists("/remote/file.txt");
|
|
128
|
+
if (exists) {
|
|
129
|
+
const data = await client.readFile("/remote/file.txt");
|
|
130
|
+
}
|
|
131
|
+
} finally {
|
|
132
|
+
await client.close();
|
|
133
|
+
}
|
|
134
|
+
```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sftp-storage-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;
|
|
1
|
+
{"version":3,"file":"sftp-storage-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAMnD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKtE;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CvD,OAAO,CAAC,cAAc;IAOtB,0CAA0C;IACpC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;;;;OAMG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQ1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAc1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,0CAA0C;IACpC,GAAG,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}
|
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import { SdError } from "@simplysm/core-common";
|
|
2
2
|
import SftpClient from "ssh2-sftp-client";
|
|
3
|
+
import fsP from "fs/promises";
|
|
4
|
+
import os from "os";
|
|
5
|
+
import pathMod from "path";
|
|
3
6
|
/**
|
|
4
7
|
* SFTP 프로토콜을 사용하는 스토리지 클라이언트.
|
|
5
8
|
*
|
|
@@ -32,9 +35,6 @@ export class SftpStorageClient {
|
|
|
32
35
|
}
|
|
33
36
|
else {
|
|
34
37
|
// SSH agent + 키 파일로 인증
|
|
35
|
-
const fsP = await import("fs/promises");
|
|
36
|
-
const os = await import("os");
|
|
37
|
-
const pathMod = await import("path");
|
|
38
38
|
const keyPath = pathMod.join(os.homedir(), ".ssh", "id_ed25519");
|
|
39
39
|
const baseOptions = {
|
|
40
40
|
host: config.host,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sftp-storage-client.js","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,UAAU,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"sftp-storage-client.js","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,UAAU,MAAM,kBAAkB,CAAC;AAC1C,OAAO,GAAG,MAAM,aAAa,CAAC;AAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,OAAO,MAAM,MAAM,CAAC;AAO3B;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IACpB,OAAO,CAAyB;IAExC;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,MAAyB;QACrC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,OAAO,CAAC,6CAA6C,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;gBAC5B,MAAM,MAAM,CAAC,OAAO,CAAC;oBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,QAAQ,EAAE,MAAM,CAAC,IAAI;oBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;iBAC1B,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,uBAAuB;gBACvB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;gBAEjE,MAAM,WAAW,GAAG;oBAClB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,QAAQ,EAAE,MAAM,CAAC,IAAI;oBACrB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACzF,CAAC;gBAEF,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,OAAO,CAAC;wBACnB,GAAG,WAAW;wBACd,UAAU,EAAE,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;qBACxC,CAAC,CAAC;gBACL,CAAC;gBAAC,MAAM,CAAC;oBACP,8CAA8C;oBAC9C,MAAM,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;YACnB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,KAAK,CAAC,OAAe;QACzB,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,MAAc;QAC3C,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,IAAI,CAAC;YACH,8DAA8D;YAC9D,kDAAkD;YAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5D,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAe;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACzB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,IAAI,KAAK,GAAG;SAC1B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,QAAgB;QAC7B,wDAAwD;QACxD,kEAAkE;QAClE,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAkB,CAAC;QAC5E,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;YACjC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,6BAA6B;QAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,GAAG,CAAC,iBAAiC,EAAE,eAAuB;QAClE,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;YAC1C,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,OAAO,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;QAC1E,CAAC;aAAM,CAAC;YACN,yFAAyF;YACzF,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,MAAc;QAC9C,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;IAC3B,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@simplysm/storage",
|
|
3
|
-
"version": "14.0.
|
|
3
|
+
"version": "14.0.4",
|
|
4
4
|
"description": "심플리즘 패키지 - 저장소 (node)",
|
|
5
5
|
"author": "심플리즘",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
"dependencies": {
|
|
21
21
|
"basic-ftp": "^5.2.0",
|
|
22
22
|
"ssh2-sftp-client": "^12.1.1",
|
|
23
|
-
"@simplysm/core-common": "14.0.
|
|
23
|
+
"@simplysm/core-common": "14.0.4"
|
|
24
24
|
},
|
|
25
25
|
"devDependencies": {
|
|
26
26
|
"@types/ssh2-sftp-client": "^9.0.6"
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import type { Bytes } from "@simplysm/core-common";
|
|
2
2
|
import { SdError } from "@simplysm/core-common";
|
|
3
3
|
import SftpClient from "ssh2-sftp-client";
|
|
4
|
+
import fsP from "fs/promises";
|
|
5
|
+
import os from "os";
|
|
6
|
+
import pathMod from "path";
|
|
4
7
|
import type { StorageClient, FileInfo } from "../types/storage";
|
|
5
8
|
import type { StorageConnConfig } from "../types/storage-conn-config";
|
|
6
9
|
|
|
@@ -40,9 +43,6 @@ export class SftpStorageClient implements StorageClient {
|
|
|
40
43
|
});
|
|
41
44
|
} else {
|
|
42
45
|
// SSH agent + 키 파일로 인증
|
|
43
|
-
const fsP = await import("fs/promises");
|
|
44
|
-
const os = await import("os");
|
|
45
|
-
const pathMod = await import("path");
|
|
46
46
|
const keyPath = pathMod.join(os.homedir(), ".ssh", "id_ed25519");
|
|
47
47
|
|
|
48
48
|
const baseOptions = {
|