lee/puter
1
0
Fork 0
mirror of https://github.com/HeyPuter/puter.git synced 2026-09-27 15:46:30 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Document the share flag and returnShares

Browse Source
This commit is contained in:
Juan Castro
2026-08-25 17:45:15 -04:00
parent 3217533594
commit 0c8dd8b6e4
4 changed files with 55 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/docs/src/FS/readdir.md
+2
View File
@@ -41,6 +41,8 @@ An object with the following properties:
A `Promise` that resolves to an array of [`FSItem`](/Objects/fsitem/) objects (files and directories) within the specified directory.
Each item carries `is_shared`: `true` when you have shared it with someone, `false` when you have not, and `null` for items that are not yours. Only shares on the item itself count — the children of a folder you shared report `false`, since the share lives on the folder. Use [`getShares()`](/FS/getShares/) on an item to see who can reach it, including access inherited from a parent.
When the request includes `cursor` (even `null`) or `includeTotal`, the promise instead resolves to a page object:
- `items` (Array): The [`FSItem`](/Objects/fsitem/) objects on this page.
src/docs/src/FS/stat.md
+32
View File
@@ -31,11 +31,16 @@ An object with the following properties:
- `returnPermissions` (Boolean) - Whether to return permission information. Defaults to `false`.
- `returnVersions` (Boolean) - Whether to return version information. Defaults to `false`.
- `returnSize` (Boolean) - Whether to return size information. Defaults to `false`.
- `returnShares` (Boolean) - Whether to include who the item is shared with, as a `shares` array on the result. Defaults to `false`.
## Return value
A `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of the specified file or directory.
The item carries `is_shared`: `true` when you have shared it with someone, `false` when you have not, and `null` when the item is not yours — whether someone else's file has other recipients is not yours to see. Only shares **on the item itself** count. A file inside a folder you shared is reachable through that folder without being shared itself, so it reports `false`; [`getShares()`](/FS/getShares/) is what reports inherited access.
With `returnShares: true`, the result also carries `shares` — an array of the same share objects [`getShares()`](/FS/getShares/) returns, including access inherited from a parent folder and unclaimed invitations. It is empty unless you own the item or hold `manage` on it, so asking for it never fails a `stat()` you were otherwise allowed to make.
## Examples
<strong class="example-title">Get information about a file</strong>
@@ -61,3 +66,30 @@ A `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of the speci
</body>
</html>
```
<strong class="example-title">See whether a file is shared, and with whom</strong>
```html;fs-stat-shares
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
await puter.fs.write('report.txt', 'Quarterly numbers');
await puter.fs.share('report.txt', 'friend@example.com', 'read');
const file = await puter.fs.stat('report.txt', { returnShares: true });
puter.print(`shared: ${file.is_shared}<br>`);
for (const share of file.shares) {
puter.print(`${share.holder ?? share.recipientEmail}: ${share.mode}<br>`);
}
})()
</script>
</body>
</html>
```
## Related
- [`puter.fs.getShares()`](/FS/getShares/) - List who can reach an item
- [`puter.fs.share()`](/FS/share/) - Grant access
src/docs/src/Objects/fsitem.md
+4
View File
@@ -40,6 +40,10 @@ An integer containing the Unix timestamp of the date and time when the item was
An integer containing the size of the item in bytes. If the item is a directory, this will be `null`.
#### `is_shared` (Boolean | null)
Whether you have shared this item with anyone: `true` if you have, `false` if you have not, and `null` when the item is not yours. Only shares on the item itself count, not access inherited from a shared parent folder. Set by [`stat()`](/FS/stat/) and [`readdir()`](/FS/readdir/); absent on items obtained any other way.
## Methods
### `read()`
src/docs/src/playground/examples/fs-stat-shares.html
+17
View File
@@ -0,0 +1,17 @@
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
await puter.fs.write('report.txt', 'Quarterly numbers');
await puter.fs.share('report.txt', 'friend@example.com', 'read');
const file = await puter.fs.stat('report.txt', { returnShares: true });
puter.print(`shared: ${file.is_shared}<br>`);
for (const share of file.shares) {
puter.print(`${share.holder ?? share.recipientEmail}: ${share.mode}<br>`);
}
})()
</script>
</body>
</html>