1 /*
2 * Copyright (C) 2020 Square, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 /**
18 * This class declares the subset of Node.js file system APIs that we need in Okio.
19 *
20 *
21 * Why not Dukat?
22 * --------------
23 *
24 * This file does manually what ideally [Dukat] would do automatically.
25 *
26 * Dukat's generated stubs need awkward call sites to disambiguate overloads. For example, to call
27 * `mkdirSync()` we must specify an options parameter even though we just want the default:
28 *
29 * mkdirSync(dir.toString(), options = undefined as MakeDirectoryOptions?)
30 *
31 * By defining our own externals, we can omit the unwanted optional parameter from the declaration.
32 * This leads to nicer calling code!
33 *
34 * mkdirSync(dir.toString())
35 *
36 * Dukat also gets the nullability wrong for `Dirent.readSync()`.
37 *
38 *
39 * Why not Kotlinx-nodejs?
40 * -----------------------
41 *
42 * Even better than using Dukat directly would be to use the [official artifact][kotlinx_nodejs],
43 * itself generated with Dukat. We also don't use the official Node.js artifact for the reasons
44 * above, and also because it has an unstable API.
45 *
46 *
47 * Updating this file
48 * ------------------
49 *
50 * To declare new external APIs, run Dukat to generate a full set of Node stubs. The easiest way to
51 * do this is to add an NPM dependency on `@types/node` in `jsMain`, like this:
52 *
53 * ```
54 * jsMain {
55 * ...
56 * dependencies {
57 * implementation(npm("@types/node", "14.14.16", true))
58 * ...
59 * }
60 * }
61 * ```
62 *
63 * This will create a file with a full set of APIs to copy-paste from.
64 *
65 * ```
66 * okio/build/externals/okio-parent-okio/src/fs.fs.module_node.kt
67 * ```
68 *
69 * [Dukat]: https://github.com/kotlin/dukat
70 * [kotlinx_nodejs]: https://github.com/Kotlin/kotlinx-nodejs
71 */
72 @file:JsModule("fs")
73 @file:JsNonModule
74
75 package okio
76
77 import kotlin.js.Date
78
closeSyncnull79 internal external fun closeSync(fd: Number)
80
81 internal external fun mkdirSync(path: String): String?
82
83 internal external fun openSync(path: String, flags: String): Double
84
85 internal external fun opendirSync(path: String): Dir
86
87 internal external fun readlinkSync(path: String): String
88
89 internal external fun readSync(fd: Number, buffer: ByteArray, offset: Double, length: Double, position: Double?): Double
90
91 internal external fun realpathSync(path: String): String
92
93 internal external fun renameSync(oldPath: String, newPath: String)
94
95 internal external fun rmdirSync(path: String)
96
97 internal external fun lstatSync(path: String): Stats
98
99 internal external fun fstatSync(fd: Number): Stats
100
101 internal external fun unlinkSync(path: String)
102
103 internal external fun writeSync(fd: Number, buffer: ByteArray): Double
104
105 internal external fun writeSync(fd: Number, buffer: ByteArray, offset: Double, length: Double, position: Double): Double
106
107 internal external fun ftruncateSync(fd: Number, len: Double)
108
109 internal external fun symlinkSync(target: String, path: String)
110
111 internal open external class Dir {
112 open var path: String
113 open fun closeSync()
114
115 // Note that dukat's signature of readSync() returns a non-nullable Dirent; that's incorrect.
116 open fun readSync(): Dirent?
117 }
118
119 internal open external class Dirent {
isFilenull120 open fun isFile(): Boolean
121 open fun isDirectory(): Boolean
122 open fun isBlockDevice(): Boolean
123 open fun isCharacterDevice(): Boolean
124 open fun isSymbolicLink(): Boolean
125 open fun isFIFO(): Boolean
126 open fun isSocket(): Boolean
127 open var name: String
128 }
129
130 internal external interface StatsBase<T> {
131 fun isFile(): Boolean
132 fun isDirectory(): Boolean
133 fun isBlockDevice(): Boolean
134 fun isCharacterDevice(): Boolean
135 fun isSymbolicLink(): Boolean
136 fun isFIFO(): Boolean
137 fun isSocket(): Boolean
138 var dev: T
139 var ino: T
140 var mode: T
141 var nlink: T
142 var uid: T
143 var gid: T
144 var rdev: T
145 var size: T
146 var blksize: T
147 var blocks: T
148 var atimeMs: T
149 var mtimeMs: T
150 var ctimeMs: T
151 var birthtimeMs: T
152 var atime: Date
153 var mtime: Date
154 var ctime: Date
155 var birthtime: Date
156 }
157
158 internal open external class Stats : StatsBase<Number> {
isFilenull159 override fun isFile(): Boolean
160 override fun isDirectory(): Boolean
161 override fun isBlockDevice(): Boolean
162 override fun isCharacterDevice(): Boolean
163 override fun isSymbolicLink(): Boolean
164 override fun isFIFO(): Boolean
165 override fun isSocket(): Boolean
166 override var dev: Number
167 override var ino: Number
168 override var mode: Number
169 override var nlink: Number
170 override var uid: Number
171 override var gid: Number
172 override var rdev: Number
173 override var size: Number
174 override var blksize: Number
175 override var blocks: Number
176 override var atimeMs: Number
177 override var mtimeMs: Number
178 override var ctimeMs: Number
179 override var birthtimeMs: Number
180 override var atime: Date
181 override var mtime: Date
182 override var ctime: Date
183 override var birthtime: Date
184 }
185