Juan Castro
cec8382d4d
Two textual conflicts, both additive on each side: `isAccountContext` (here) and `isPlainUserActor` (main) are both imported and both used, and the `stat()` note keeps both sentences — this branch's on who may read an invite address, main's on the share-read limit it spends. The rest is adapting to main, which grew its own answer to half of what this branch was for. `listSharesOf` there bounds an app to the rows it issued itself; this branch instead required the credential to hold `manage` and refused it otherwise. Main's is the better mechanism — it answers the app rather than turning it away, and it hides other issuers' rows outright rather than redacting a field on them — so the `manage` gate goes, and with it the two tests that asserted the refusal. They are replaced by tests that hold main's line: an app sees none of the invites it did not send, with or without `manage`. What this branch still carries is the gap main does not close. Its row filter only applies to apps, so a plain manage delegate still reads the owner's invite addresses; `#maySeeInviteAddress` is what withholds those, and its delegate tests pass unchanged. The `stat()` note is corrected to describe main's behaviour rather than the removed gate.
4.3 KiB
Executable File
title, description, platforms
| title | description | platforms | ||||
|---|---|---|---|---|---|---|
| puter.fs.stat() | Get file or directory information in the user's own Puter file system. |
|
This method allows you to get information about a file or directory.
Syntax
puter.fs.stat(path, options)
puter.fs.stat(options)
Parameters
path (String) (required)
The path to the file or directory to get information about.
If path is not absolute, it will be resolved relative to the app's root directory.
options (Object) (optional)
An object with the following properties:
path(String) - Path to the file or directory. Required when passing options as the only argument.uid(String) - The UID of the file or directory. Can be used instead ofpath.returnSubdomains(Boolean) - Whether to return subdomain information. Defaults tofalse.returnWorkers(Boolean) - Whether to return the workers attached to the item. Workers are served alongside subdomains, so this is an alias ofreturnSubdomains— setting either one returns both. Defaults tofalse.returnPermissions(Boolean) - Whether to return permission information. Defaults tofalse.returnVersions(Boolean) - Whether to return version information. Defaults tofalse.returnSize(Boolean) - Whether to return size information. Defaults tofalse.returnShares(Boolean) - Whether to include who the item is shared with, as asharesarray on the result. Defaults tofalse.
Return value
A Promise that resolves to the FSItem object of the specified file or directory.
The item carries is_shared: true when it has been shared with someone, false when it has not, and null when the item is not yours — whether someone else's file has other recipients is not yours to see. It covers shares granted by anyone holding manage on the item, not only your own, the same way getShares() does. 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() is what reports inherited access.
With returnShares: true, the result also carries shares — an array of the same share objects 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. An app or API token sees only the shares it issued itself, and an invitation's recipientEmail is withheld from everyone but the owner and its sender — see getShares(). Because it does getShares()'s work, it also spends from the share-read limit on top of stat()'s own.
Examples
Get information about a file
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
// () create a file
await puter.fs.write('hello.txt', 'Hello, world!');
puter.print('hello.txt created<br>');
// (2) get information about hello.txt
const file = await puter.fs.stat('hello.txt');
puter.print(`hello.txt name: ${file.name}<br>`);
puter.print(`hello.txt path: ${file.path}<br>`);
puter.print(`hello.txt size: ${file.size}<br>`);
puter.print(`hello.txt created: ${file.created}<br>`);
})()
</script>
</body>
</html>
See whether a file is shared, and with whom
<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()- List who can reach an itemputer.fs.share()- Grant access