81795744cf
* fix: ensure the typescript definitions only export correct value types In typescript there are two main types of "types" you can export, value types (class, const) and definition types (type, interface). The typescript compiler will let anything declared via const or class be used as a value. Unfortunately we were exporting a bunch of things (see the diff) as class/const when they weren't actually exported values. This lead to typescript being happy but the runtime throwing errors (not something we want). This change passes "exported-in" context through our docs, to the parser and then to the definitions generator to ensure we only mark things as exported in the ts defs that we actually export. Fixes #22167 * chore: update typescript-defs * chore: update typescript-defs * chore: fix bad typescript in IPC test * docs: test rendering of new syntax * chore: update per feedback, use same syntax but with 'this is not exportedd' line
121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
## Class: Cookies
|
|
|
|
> Query and modify a session's cookies.
|
|
|
|
Process: [Main](../glossary.md#main-process)<br />
|
|
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
|
|
|
|
Instances of the `Cookies` class are accessed by using `cookies` property of
|
|
a `Session`.
|
|
|
|
For example:
|
|
|
|
```javascript
|
|
const { session } = require('electron')
|
|
|
|
// Query all cookies.
|
|
session.defaultSession.cookies.get({})
|
|
.then((cookies) => {
|
|
console.log(cookies)
|
|
}).catch((error) => {
|
|
console.log(error)
|
|
})
|
|
|
|
// Query all cookies associated with a specific url.
|
|
session.defaultSession.cookies.get({ url: 'http://www.github.com' })
|
|
.then((cookies) => {
|
|
console.log(cookies)
|
|
}).catch((error) => {
|
|
console.log(error)
|
|
})
|
|
|
|
// Set a cookie with the given cookie data;
|
|
// may overwrite equivalent cookies if they exist.
|
|
const cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }
|
|
session.defaultSession.cookies.set(cookie)
|
|
.then(() => {
|
|
// success
|
|
}, (error) => {
|
|
console.error(error)
|
|
})
|
|
```
|
|
|
|
### Instance Events
|
|
|
|
The following events are available on instances of `Cookies`:
|
|
|
|
#### Event: 'changed'
|
|
|
|
Returns:
|
|
|
|
* `event` Event
|
|
* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed.
|
|
* `cause` String - The cause of the change with one of the following values:
|
|
* `explicit` - The cookie was changed directly by a consumer's action.
|
|
* `overwrite` - The cookie was automatically removed due to an insert
|
|
operation that overwrote it.
|
|
* `expired` - The cookie was automatically removed as it expired.
|
|
* `evicted` - The cookie was automatically evicted during garbage collection.
|
|
* `expired-overwrite` - The cookie was overwritten with an already-expired
|
|
expiration date.
|
|
* `removed` Boolean - `true` if the cookie was removed, `false` otherwise.
|
|
|
|
Emitted when a cookie is changed because it was added, edited, removed, or
|
|
expired.
|
|
|
|
### Instance Methods
|
|
|
|
The following methods are available on instances of `Cookies`:
|
|
|
|
#### `cookies.get(filter)`
|
|
|
|
* `filter` Object
|
|
* `url` String (optional) - Retrieves cookies which are associated with
|
|
`url`. Empty implies retrieving cookies of all URLs.
|
|
* `name` String (optional) - Filters cookies by name.
|
|
* `domain` String (optional) - Retrieves cookies whose domains match or are
|
|
subdomains of `domains`.
|
|
* `path` String (optional) - Retrieves cookies whose path matches `path`.
|
|
* `secure` Boolean (optional) - Filters cookies by their Secure property.
|
|
* `session` Boolean (optional) - Filters out session or persistent cookies.
|
|
|
|
Returns `Promise<Cookie[]>` - A promise which resolves an array of cookie objects.
|
|
|
|
Sends a request to get all cookies matching `filter`, and resolves a promise with
|
|
the response.
|
|
|
|
#### `cookies.set(details)`
|
|
|
|
* `details` Object
|
|
* `url` String - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.
|
|
* `name` String (optional) - The name of the cookie. Empty by default if omitted.
|
|
* `value` String (optional) - The value of the cookie. Empty by default if omitted.
|
|
* `domain` String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains. Empty by default if omitted.
|
|
* `path` String (optional) - The path of the cookie. Empty by default if omitted.
|
|
* `secure` Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to
|
|
false.
|
|
* `httpOnly` Boolean (optional) - Whether the cookie should be marked as HTTP only.
|
|
Defaults to false.
|
|
* `expirationDate` Double (optional) - The expiration date of the cookie as the number of
|
|
seconds since the UNIX epoch. If omitted then the cookie becomes a session
|
|
cookie and will not be retained between sessions.
|
|
* `sameSite` String (optional) - The [Same Site](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#SameSite_cookies) policy to apply to this cookie. Can be `unspecified`, `no_restriction`, `lax` or `strict`. Default is `no_restriction`.
|
|
|
|
Returns `Promise<void>` - A promise which resolves when the cookie has been set
|
|
|
|
Sets a cookie with `details`.
|
|
|
|
#### `cookies.remove(url, name)`
|
|
|
|
* `url` String - The URL associated with the cookie.
|
|
* `name` String - The name of cookie to remove.
|
|
|
|
Returns `Promise<void>` - A promise which resolves when the cookie has been removed
|
|
|
|
Removes the cookies matching `url` and `name`
|
|
|
|
#### `cookies.flushStore()`
|
|
|
|
Returns `Promise<void>` - A promise which resolves when the cookie store has been flushed
|
|
|
|
Writes any unwritten cookies data to disk.
|