@thingmate/abilities 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,7 @@
 ![npm](https://img.shields.io/npm/dm/@thingmate/abilities.svg)
 ![NPM](https://img.shields.io/npm/l/@thingmate/abilities.svg)
 ![npm type definitions](https://img.shields.io/npm/types/@thingmate/abilities.svg)
+![AI generation](https://img.shields.io/badge/AI_generation-low-yellow)
 
 <picture>
   <source height="64" media="(prefers-color-scheme: dark)" srcset="https://github.com/thingmate/website/blob/main/assets/logo/png/logo-large-dark.png?raw=true">
@@ -23,4 +24,191 @@ npm install @thingmate/abilities --save
 
 ## 📜 Documentation
 
-TODO
+This library defines generic **abilities**: minimal and composable interfaces describing what a
+_thing_ can do.
+
+They are built on top of
+[`@xstd/async-function`](https://www.npmjs.com/package/@xstd/async-function) and
+[`@xstd/observable-async-function`](https://www.npmjs.com/package/@xstd/observable-async-function):
+
+- [`SendAction`](#sendaction) - send (trigger) something with arguments, without expecting a result
+- [`ReadAction`](#readaction) - read and return a value
+- [`WriteAction`](#writeaction) - write a value
+- [`ObserveAbility`](#observeability) - observe values over time
+- [`CommandAbilities`](#commandabilities) - send a command and observe it
+- [`ReadonlyPropertyAbilities`](#readonlypropertyabilities) - read a value and observe its changes
+- [`PropertyAbilities`](#propertyabilities) - read, write and observe a value
+
+Each ability also exists as a `Having*` structural interface (see [Abilities](#abilities)): any
+object exposing the matching properties fulfills it, no base class is required.
+
+### Actions
+
+Actions are abortable async functions: every call takes a leading `AbortSignal`, followed by the
+action's arguments, and returns a promise.
+
+| Action                   | Equivalent to                     | Description                                             |
+| ------------------------ | --------------------------------- | ------------------------------------------------------- |
+| `SendAction<GArguments>` | `AsyncFunction<GArguments, void>` | Sends (triggers) something with the provided arguments. |
+| `ReadAction<GValue>`     | `AsyncFunction<[], GValue>`       | Reads and returns the current value.                    |
+| `WriteAction<GValue>`    | `AsyncFunction<[GValue], void>`   | Writes the provided value.                              |
+
+```ts
+import { AsyncFunction } from '@xstd/async-function';
+import type { ReadAction, WriteAction } from '@thingmate/abilities';
+
+const readTemperature: ReadAction<number> = new AsyncFunction(async () => sensor.temperature);
+
+const setTemperature: WriteAction<number> = new AsyncFunction(async (signal, value: number) => {
+  await sensor.setTemperature(value, { signal });
+});
+
+const current: number = await readTemperature.call(signal);
+await setTemperature.call(signal, 21.5);
+```
+
+### Abilities
+
+The `Having*` interfaces declare the abilities exposed by an object.
+
+| Interface                                  | Exposed property                                       |
+| ------------------------------------------ | ------------------------------------------------------ |
+| `HavingSendAbility<GArguments>`            | `send: SendAction<GArguments>`                         |
+| `HavingReadAbility<GValue>`                | `read: ReadAction<GValue>`                             |
+| `HavingWriteAbility<GValue>`               | `write: WriteAction<GValue>`                           |
+| `HavingObserveAbility<GValue, GArguments>` | `observe: ObservableAsyncFunction<GValue, GArguments>` |
+
+```ts
+import type { HavingReadAbility, HavingWriteAbility } from '@thingmate/abilities';
+
+interface Thermostat extends HavingReadAbility<number>, HavingWriteAbility<number> {}
+```
+
+### ObserveAbility
+
+The ability to observe values over time, wrapping an `ObservableAsyncFunction`: calling `observe`
+establishes a live resource emitting the observed values.
+
+```ts
+import { ObserveAbility } from '@thingmate/abilities';
+
+const temperature: ObserveAbility<number> = new ObserveAbility(temperatureChanges);
+
+for await (const value of temperature.observe.values(signal)) {
+  console.log(value); // every emitted temperature
+}
+```
+
+### CommandAbilities
+
+The abilities of a command: sending it (`send`) and observing it (`observe`).
+
+The observed values are typed with the command's own arguments tuple: a command accepting
+`[celsius: number]` observes values of type `[celsius: number]`.
+
+```ts
+import { AsyncFunction } from '@xstd/async-function';
+import { CommandAbilities } from '@thingmate/abilities';
+
+const setCelsius: CommandAbilities<[celsius: number]> = new CommandAbilities({
+  send: new AsyncFunction(async (signal, celsius: number) => {
+    await thermostat.setTargetTemperature(celsius, { signal });
+  }),
+  observe: targetTemperatureChanges, // an `ObservableAsyncFunction<[celsius: number]>`
+});
+
+await setCelsius.send.call(signal, 21.5);
+
+for await (const [celsius] of setCelsius.observe.values(signal)) {
+  console.log(celsius);
+}
+```
+
+`map` retypes the command: the returned `send` accepts the new arguments and maps them back to the
+original ones with `outIn`, while the observed values are mapped with `inOut`. Both are mapped
+tuple-wise.
+
+```ts
+const setFahrenheit: CommandAbilities<[fahrenheit: number]> = setCelsius.map({
+  inOut: ([celsius]) => [celsius * 1.8 + 32],
+  outIn: ([fahrenheit]) => [(fahrenheit - 32) / 1.8],
+});
+
+await setFahrenheit.send.call(signal, 70); // sends the command with ~21.1°C
+```
+
+Its structural counterpart is `HavingCommandAbilities<GArguments>`.
+
+### ReadonlyPropertyAbilities
+
+The abilities of a readonly property: reading its current value (`read`) and observing its changes
+over time (`observe`).
+
+```ts
+import { AsyncFunction } from '@xstd/async-function';
+import { ReadonlyPropertyAbilities } from '@thingmate/abilities';
+
+const temperature: ReadonlyPropertyAbilities<number> = new ReadonlyPropertyAbilities({
+  read: new AsyncFunction(async () => sensor.temperature),
+  observe: temperatureChanges, // an `ObservableAsyncFunction<number>`
+});
+
+const current: number = await temperature.read.call(signal);
+
+for await (const value of temperature.observe.values(signal)) {
+  console.log(value); // every temperature change
+}
+```
+
+`map` retypes the property with a single mapping function applied to the read and observed values.
+
+```ts
+const fahrenheit: ReadonlyPropertyAbilities<number> = temperature.map(
+  (celsius: number): number => celsius * 1.8 + 32,
+);
+```
+
+Its structural counterpart is `HavingReadonlyPropertyAbilities<GValue>`.
+
+### PropertyAbilities
+
+The abilities of a property: reading its current value (`read`), writing it (`write`), and
+observing its changes over time (`observe`).
+
+```ts
+import { AsyncFunction } from '@xstd/async-function';
+import { PropertyAbilities } from '@thingmate/abilities';
+
+const temperature: PropertyAbilities<number> = new PropertyAbilities({
+  read: new AsyncFunction(async () => sensor.temperature),
+  write: new AsyncFunction(async (signal, value: number) => {
+    await sensor.setTemperature(value, { signal });
+  }),
+  observe: temperatureChanges, // an `ObservableAsyncFunction<number>`
+});
+
+const current: number = await temperature.read.call(signal);
+await temperature.write.call(signal, 21.5);
+
+for await (const value of temperature.observe.values(signal)) {
+  console.log(value); // every temperature change
+}
+```
+
+`map` retypes the property with a bi-directional mapping: values read from, or observed through, the
+returned property are mapped with `inOut`, while values written to it are mapped back with `outIn`.
+
+```ts
+const fahrenheit: PropertyAbilities<number> = temperature.map({
+  inOut: (celsius) => celsius * 1.8 + 32,
+  outIn: (fahrenheit) => (fahrenheit - 32) / 1.8,
+});
+```
+
+`asReadonly` returns a readonly view of the property, without the `write` ability.
+
+```ts
+const readonlyTemperature: ReadonlyPropertyAbilities<number> = temperature.asReadonly();
+```
+
+Its structural counterpart is `HavingPropertyAbilities<GValue>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thingmate/abilities",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Generic abilities interfaces",
   "keywords": [],

package/src/combined/command/command-abilities.d.ts

@@ -2,10 +2,53 @@ import type { MapInOut } from '@xstd/map-function';
 import type { ObservableAsyncFunction } from '@xstd/observable-async-function';
 import type { SendAction } from '../../individual/send/send-action.ts';
 import type { HavingCommandAbilities } from './having-command-abilities.ts';
+/**
+ * The abilities of a command: sending it ({@link SendAction}) and observing it
+ * ({@link ObservableAsyncFunction}).
+ *
+ * The observed values are typed with the command's own arguments tuple: a command accepting
+ * `[volume: number]` observes values of type `[volume: number]`.
+ *
+ * @template GArguments - The tuple type of the arguments accepted by the command.
+ *
+ * @example
+ * ```ts
+ * const setVolume: CommandAbilities<[volume: number]> = new CommandAbilities({
+ *   send: new AsyncFunction(async (signal, volume: number): Promise<void> => {
+ *     await device.setVolume(volume, { signal });
+ *   }),
+ *   observe: volumeChanges, // an `ObservableAsyncFunction<[volume: number]>`
+ * });
+ *
+ * await setVolume.send.call(signal, 50);
+ * ```
+ */
 export declare class CommandAbilities<GArguments extends readonly unknown[]> implements HavingCommandAbilities<GArguments> {
     #private;
+    /**
+     * Creates a new {@link CommandAbilities}.
+     *
+     * @param abilities - The abilities to wrap.
+     * @param abilities.send - The action invoked when the command is sent.
+     * @param abilities.observe - The observable async function emitting the command's events.
+     */
     constructor({ send, observe }: HavingCommandAbilities<GArguments>);
+    /** The action invoked when the command is sent. */
     get send(): SendAction<GArguments>;
+    /** The observable async function emitting the command's events. */
     get observe(): ObservableAsyncFunction<GArguments>;
+    /**
+     * Maps these command abilities to work with different arguments.
+     *
+     * The send action of the returned command abilities accepts `GNewArguments` and maps them back to
+     * this command's arguments with `outIn`, while the values emitted by its observation are mapped
+     * to the new type with `inOut`.
+     *
+     * @template GNewArguments - The tuple type of the arguments of the returned command abilities.
+     * @param mapping - The bi-directional mapping between this command's arguments and the new ones.
+     * @param mapping.inOut - Maps this command's arguments into the new ones.
+     * @param mapping.outIn - Maps the new arguments into this command's arguments.
+     * @returns New command abilities working with `GNewArguments`.
+     */
     map<GNewArguments extends readonly unknown[]>({ inOut, outIn, }: MapInOut<GArguments, GNewArguments>): CommandAbilities<GNewArguments>;
 }

package/src/combined/command/command-abilities.js

@@ -1,16 +1,59 @@
+/**
+ * The abilities of a command: sending it ({@link SendAction}) and observing it
+ * ({@link ObservableAsyncFunction}).
+ *
+ * The observed values are typed with the command's own arguments tuple: a command accepting
+ * `[volume: number]` observes values of type `[volume: number]`.
+ *
+ * @template GArguments - The tuple type of the arguments accepted by the command.
+ *
+ * @example
+ * ```ts
+ * const setVolume: CommandAbilities<[volume: number]> = new CommandAbilities({
+ *   send: new AsyncFunction(async (signal, volume: number): Promise<void> => {
+ *     await device.setVolume(volume, { signal });
+ *   }),
+ *   observe: volumeChanges, // an `ObservableAsyncFunction<[volume: number]>`
+ * });
+ *
+ * await setVolume.send.call(signal, 50);
+ * ```
+ */
 export class CommandAbilities {
     #send;
     #observe;
+    /**
+     * Creates a new {@link CommandAbilities}.
+     *
+     * @param abilities - The abilities to wrap.
+     * @param abilities.send - The action invoked when the command is sent.
+     * @param abilities.observe - The observable async function emitting the command's events.
+     */
     constructor({ send, observe }) {
         this.#send = send;
         this.#observe = observe;
     }
+    /** The action invoked when the command is sent. */
     get send() {
         return this.#send;
     }
+    /** The observable async function emitting the command's events. */
     get observe() {
         return this.#observe;
     }
+    /**
+     * Maps these command abilities to work with different arguments.
+     *
+     * The send action of the returned command abilities accepts `GNewArguments` and maps them back to
+     * this command's arguments with `outIn`, while the values emitted by its observation are mapped
+     * to the new type with `inOut`.
+     *
+     * @template GNewArguments - The tuple type of the arguments of the returned command abilities.
+     * @param mapping - The bi-directional mapping between this command's arguments and the new ones.
+     * @param mapping.inOut - Maps this command's arguments into the new ones.
+     * @param mapping.outIn - Maps the new arguments into this command's arguments.
+     * @returns New command abilities working with `GNewArguments`.
+     */
     map({ inOut, outIn, }) {
         return new CommandAbilities({
             send: this.#send.mapArguments((...args) => {

package/src/combined/command/command-abilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-abilities.js","sourceRoot":"","sources":["../../../../src/combined/command/command-abilities.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,gBAAgB;IAGlB,KAAK,CAAyB;IAC9B,QAAQ,CAAsC;IAEvD,YAAY,EAAE,IAAI,EAAE,OAAO,EAAsC;QAC/D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG,CAA2C,EAC5C,KAAK,EACL,KAAK,GAC+B;QACpC,OAAO,IAAI,gBAAgB,CAAgB;YACzC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,IAAmB,EAAc,EAAE;gBACnE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC,CAAC;YACF,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"command-abilities.js","sourceRoot":"","sources":["../../../../src/combined/command/command-abilities.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,gBAAgB;IAGlB,KAAK,CAAyB;IAC9B,QAAQ,CAAsC;IAEvD;;;;;;OAMG;IACH,YAAY,EAAE,IAAI,EAAE,OAAO,EAAsC;QAC/D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,mDAAmD;IACnD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,mEAAmE;IACnE,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,GAAG,CAA2C,EAC5C,KAAK,EACL,KAAK,GAC+B;QACpC,OAAO,IAAI,gBAAgB,CAAgB;YACzC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,IAAmB,EAAc,EAAE;gBACnE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC,CAAC;YACF,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;CACF"}

package/src/combined/command/having-command-abilities.d.ts

@@ -1,4 +1,10 @@
 import type { HavingObserveAbility } from '../../individual/observe/having-observe-ability.ts';
 import type { HavingSendAbility } from '../../individual/send/having-send-ability.ts';
+/**
+ * An object having the abilities of a command: sending it ({@link HavingSendAbility}) and observing
+ * it ({@link HavingObserveAbility}).
+ *
+ * @template GArguments - The tuple type of the arguments accepted by the command.
+ */
 export interface HavingCommandAbilities<GArguments extends readonly unknown[]> extends HavingSendAbility<GArguments>, HavingObserveAbility<GArguments> {
 }

package/src/combined/property/having-property-abilities.d.ts

@@ -1,4 +1,10 @@
 import type { HavingWriteAbility } from '../../individual/write/having-write-ability.ts';
 import type { HavingReadonlyPropertyAbilities } from './readonly/having-readonly-property-abilities.ts';
+/**
+ * An object having the abilities of a property: reading and observing it
+ * ({@link HavingReadonlyPropertyAbilities}) and writing it ({@link HavingWriteAbility}).
+ *
+ * @template GValue - The type of the property's value.
+ */
 export interface HavingPropertyAbilities<GValue> extends HavingReadonlyPropertyAbilities<GValue>, HavingWriteAbility<GValue> {
 }

package/src/combined/property/property-abilities.d.ts

@@ -4,12 +4,62 @@ import type { ReadAction } from '../../individual/read/read-action.ts';
 import type { WriteAction } from '../../individual/write/write-action.ts';
 import type { HavingPropertyAbilities } from './having-property-abilities.ts';
 import { ReadonlyPropertyAbilities } from './readonly/readonly-property-abilities.ts';
+/**
+ * The abilities of a property: reading its current value ({@link ReadAction}), writing it
+ * ({@link WriteAction}), and observing its changes over time ({@link ObservableAsyncFunction}).
+ *
+ * @template GValue - The type of the property's value.
+ *
+ * @example
+ * ```ts
+ * const temperature: PropertyAbilities<number> = new PropertyAbilities({
+ *   read: new AsyncFunction(async () => sensor.temperature),
+ *   write: new AsyncFunction(async (signal, value: number): Promise<void> => {
+ *     await sensor.setTemperature(value, { signal });
+ *   }),
+ *   observe: temperatureChanges, // an `ObservableAsyncFunction<number>`
+ * });
+ *
+ * const current: number = await temperature.read.call(signal);
+ * await temperature.write.call(signal, 21.5);
+ * ```
+ */
 export declare class PropertyAbilities<GValue> implements HavingPropertyAbilities<GValue> {
     #private;
+    /**
+     * Creates a new {@link PropertyAbilities}.
+     *
+     * @param abilities - The abilities to wrap.
+     * @param abilities.read - The action reading the property's current value.
+     * @param abilities.write - The action writing the property's value.
+     * @param abilities.observe - The observable async function emitting the property's changes.
+     */
     constructor({ read, write, observe }: HavingPropertyAbilities<GValue>);
+    /** The action reading the property's current value. */
     get read(): ReadAction<GValue>;
+    /** The action writing the property's value. */
     get write(): WriteAction<GValue>;
+    /** The observable async function emitting the property's changes. */
     get observe(): ObservableAsyncFunction<GValue>;
+    /**
+     * Maps these property abilities to work with a different value type.
+     *
+     * Values read from, or observed through, the returned property abilities are mapped with `inOut`,
+     * while values written to them are mapped back to this property's value type with `outIn`.
+     *
+     * @template GNewValue - The type of the value of the returned property abilities.
+     * @param mapping - The bi-directional mapping between this property's value and the new one.
+     * @param mapping.inOut - Maps this property's value into the new one.
+     * @param mapping.outIn - Maps the new value into this property's value.
+     * @returns New property abilities working with `GNewValue`.
+     */
     map<GNewValue>({ inOut, outIn }: MapInOut<GValue, GNewValue>): PropertyAbilities<GNewValue>;
+    /**
+     * Returns a readonly view of these property abilities.
+     *
+     * The returned instance exposes the same read and observe abilities, without the write ability.
+     *
+     * @returns New readonly property abilities reading from, and observing, this property.
+     */
     asReadonly(): ReadonlyPropertyAbilities<GValue>;
 }

package/src/combined/property/property-abilities.js

@@ -1,23 +1,66 @@
 import { mapOneArgument } from '@xstd/map-function';
 import { ReadonlyPropertyAbilities } from './readonly/readonly-property-abilities.js';
+/**
+ * The abilities of a property: reading its current value ({@link ReadAction}), writing it
+ * ({@link WriteAction}), and observing its changes over time ({@link ObservableAsyncFunction}).
+ *
+ * @template GValue - The type of the property's value.
+ *
+ * @example
+ * ```ts
+ * const temperature: PropertyAbilities<number> = new PropertyAbilities({
+ *   read: new AsyncFunction(async () => sensor.temperature),
+ *   write: new AsyncFunction(async (signal, value: number): Promise<void> => {
+ *     await sensor.setTemperature(value, { signal });
+ *   }),
+ *   observe: temperatureChanges, // an `ObservableAsyncFunction<number>`
+ * });
+ *
+ * const current: number = await temperature.read.call(signal);
+ * await temperature.write.call(signal, 21.5);
+ * ```
+ */
 export class PropertyAbilities {
     #read;
     #write;
     #observe;
+    /**
+     * Creates a new {@link PropertyAbilities}.
+     *
+     * @param abilities - The abilities to wrap.
+     * @param abilities.read - The action reading the property's current value.
+     * @param abilities.write - The action writing the property's value.
+     * @param abilities.observe - The observable async function emitting the property's changes.
+     */
     constructor({ read, write, observe }) {
         this.#read = read;
         this.#write = write;
         this.#observe = observe;
     }
+    /** The action reading the property's current value. */
     get read() {
         return this.#read;
     }
+    /** The action writing the property's value. */
     get write() {
         return this.#write;
     }
+    /** The observable async function emitting the property's changes. */
     get observe() {
         return this.#observe;
     }
+    /**
+     * Maps these property abilities to work with a different value type.
+     *
+     * Values read from, or observed through, the returned property abilities are mapped with `inOut`,
+     * while values written to them are mapped back to this property's value type with `outIn`.
+     *
+     * @template GNewValue - The type of the value of the returned property abilities.
+     * @param mapping - The bi-directional mapping between this property's value and the new one.
+     * @param mapping.inOut - Maps this property's value into the new one.
+     * @param mapping.outIn - Maps the new value into this property's value.
+     * @returns New property abilities working with `GNewValue`.
+     */
     map({ inOut, outIn }) {
         return new PropertyAbilities({
             read: this.#read.then(inOut),
@@ -25,6 +68,13 @@ export class PropertyAbilities {
             observe: this.#observe.map(inOut),
         });
     }
+    /**
+     * Returns a readonly view of these property abilities.
+     *
+     * The returned instance exposes the same read and observe abilities, without the write ability.
+     *
+     * @returns New readonly property abilities reading from, and observing, this property.
+     */
     asReadonly() {
         return new ReadonlyPropertyAbilities({
             read: this.#read,

package/src/combined/property/property-abilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"property-abilities.js","sourceRoot":"","sources":["../../../../src/combined/property/property-abilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAEtF,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAqB;IAC1B,MAAM,CAAsB;IAC5B,QAAQ,CAAkC;IAEnD,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAmC;QACnE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG,CAAY,EAAE,KAAK,EAAE,KAAK,EAA+B;QAC1D,OAAO,IAAI,iBAAiB,CAAY;YACtC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAC5B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACtD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAED,UAAU;QACR,OAAO,IAAI,yBAAyB,CAAS;YAC3C,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,OAAO,EAAE,IAAI,CAAC,QAAQ;SACvB,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"property-abilities.js","sourceRoot":"","sources":["../../../../src/combined/property/property-abilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAqB;IAC1B,MAAM,CAAsB;IAC5B,QAAQ,CAAkC;IAEnD;;;;;;;OAOG;IACH,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAmC;QACnE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,uDAAuD;IACvD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,+CAA+C;IAC/C,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,qEAAqE;IACrE,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,GAAG,CAAY,EAAE,KAAK,EAAE,KAAK,EAA+B;QAC1D,OAAO,IAAI,iBAAiB,CAAY;YACtC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAC5B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACtD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,UAAU;QACR,OAAO,IAAI,yBAAyB,CAAS;YAC3C,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,OAAO,EAAE,IAAI,CAAC,QAAQ;SACvB,CAAC,CAAC;IACL,CAAC;CACF"}

package/src/combined/property/readonly/having-readonly-property-abilities.d.ts

@@ -1,4 +1,10 @@
 import type { HavingObserveAbility } from '../../../individual/observe/having-observe-ability.ts';
 import type { HavingReadAbility } from '../../../individual/read/having-read-ability.ts';
+/**
+ * An object having the abilities of a readonly property: reading it ({@link HavingReadAbility}) and
+ * observing it ({@link HavingObserveAbility}).
+ *
+ * @template GValue - The type of the property's value.
+ */
 export interface HavingReadonlyPropertyAbilities<GValue> extends HavingReadAbility<GValue>, HavingObserveAbility<GValue> {
 }

package/src/combined/property/readonly/readonly-property-abilities.d.ts

@@ -2,10 +2,35 @@ import { type MapFunction } from '@xstd/map-function';
 import type { ObservableAsyncFunction } from '@xstd/observable-async-function';
 import type { ReadAction } from '../../../individual/read/read-action.ts';
 import type { HavingReadonlyPropertyAbilities } from './having-readonly-property-abilities.ts';
+/**
+ * The abilities of a readonly property: reading its current value ({@link ReadAction}) and
+ * observing its changes over time ({@link ObservableAsyncFunction}).
+ *
+ * @template GValue - The type of the property's value.
+ */
 export declare class ReadonlyPropertyAbilities<GValue> implements HavingReadonlyPropertyAbilities<GValue> {
     #private;
+    /**
+     * Creates a new {@link ReadonlyPropertyAbilities}.
+     *
+     * @param abilities - The abilities to wrap.
+     * @param abilities.read - The action reading the property's current value.
+     * @param abilities.observe - The observable async function emitting the property's changes.
+     */
     constructor({ read, observe }: HavingReadonlyPropertyAbilities<GValue>);
+    /** The action reading the property's current value. */
     get read(): ReadAction<GValue>;
+    /** The observable async function emitting the property's changes. */
     get observe(): ObservableAsyncFunction<GValue>;
+    /**
+     * Maps these readonly property abilities to work with a different value type.
+     *
+     * Values read from, or observed through, the returned property abilities are mapped with the
+     * provided function.
+     *
+     * @template GNewValue - The type of the value of the returned property abilities.
+     * @param map - A function mapping this property's value into the new one.
+     * @returns New readonly property abilities working with `GNewValue`.
+     */
     map<GNewValue>(map: MapFunction<GValue, GNewValue>): ReadonlyPropertyAbilities<GNewValue>;
 }

package/src/combined/property/readonly/readonly-property-abilities.js

@@ -1,17 +1,42 @@
 import {} from '@xstd/map-function';
+/**
+ * The abilities of a readonly property: reading its current value ({@link ReadAction}) and
+ * observing its changes over time ({@link ObservableAsyncFunction}).
+ *
+ * @template GValue - The type of the property's value.
+ */
 export class ReadonlyPropertyAbilities {
     #read;
     #observe;
+    /**
+     * Creates a new {@link ReadonlyPropertyAbilities}.
+     *
+     * @param abilities - The abilities to wrap.
+     * @param abilities.read - The action reading the property's current value.
+     * @param abilities.observe - The observable async function emitting the property's changes.
+     */
     constructor({ read, observe }) {
         this.#read = read;
         this.#observe = observe;
     }
+    /** The action reading the property's current value. */
     get read() {
         return this.#read;
     }
+    /** The observable async function emitting the property's changes. */
     get observe() {
         return this.#observe;
     }
+    /**
+     * Maps these readonly property abilities to work with a different value type.
+     *
+     * Values read from, or observed through, the returned property abilities are mapped with the
+     * provided function.
+     *
+     * @template GNewValue - The type of the value of the returned property abilities.
+     * @param map - A function mapping this property's value into the new one.
+     * @returns New readonly property abilities working with `GNewValue`.
+     */
     map(map) {
         return new ReadonlyPropertyAbilities({
             read: this.#read.then(map),

package/src/combined/property/readonly/readonly-property-abilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"readonly-property-abilities.js","sourceRoot":"","sources":["../../../../../src/combined/property/readonly/readonly-property-abilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,oBAAoB,CAAC;AAKtD,MAAM,OAAO,yBAAyB;IAC3B,KAAK,CAAqB;IAC1B,QAAQ,CAAkC;IAEnD,YAAY,EAAE,IAAI,EAAE,OAAO,EAA2C;QACpE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG,CAAY,GAAmC;QAChD,OAAO,IAAI,yBAAyB,CAAY;YAC9C,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1B,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"readonly-property-abilities.js","sourceRoot":"","sources":["../../../../../src/combined/property/readonly/readonly-property-abilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,oBAAoB,CAAC;AAKtD;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IAC3B,KAAK,CAAqB;IAC1B,QAAQ,CAAkC;IAEnD;;;;;;OAMG;IACH,YAAY,EAAE,IAAI,EAAE,OAAO,EAA2C;QACpE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,uDAAuD;IACvD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,qEAAqE;IACrE,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;;;OASG;IACH,GAAG,CAAY,GAAmC;QAChD,OAAO,IAAI,yBAAyB,CAAY;YAC9C,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1B,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;CACF"}

package/src/individual/observe/having-observe-ability.d.ts

@@ -1,4 +1,12 @@
 import type { ObservableAsyncFunction } from '@xstd/observable-async-function';
+/**
+ * An object having the ability to observe values over time: it exposes an
+ * {@link ObservableAsyncFunction}.
+ *
+ * @template GValue - The type of the observed values.
+ * @template GArguments - The tuple type of the extra arguments passed at observation time.
+ */
 export interface HavingObserveAbility<GValue, GArguments extends readonly unknown[] = []> {
+    /** Observes values over time: calling it establishes a live resource emitting the values. */
     readonly observe: ObservableAsyncFunction<GValue, GArguments>;
 }

package/src/individual/observe/observe-ability.d.ts

@@ -1,7 +1,28 @@
 import type { ObservableAsyncFunction } from '@xstd/observable-async-function';
 import type { HavingObserveAbility } from './having-observe-ability.ts';
+/**
+ * The ability to observe values over time, wrapping an {@link ObservableAsyncFunction}.
+ *
+ * @template GValue - The type of the observed values.
+ * @template GArguments - The tuple type of the extra arguments passed at observation time.
+ *
+ * @example
+ * ```ts
+ * const temperature: ObserveAbility<number> = new ObserveAbility(temperatureChanges);
+ *
+ * for await (const value of temperature.observe.values(signal)) {
+ *   console.log(value); // every emitted temperature
+ * }
+ * ```
+ */
 export declare class ObserveAbility<GValue, GArguments extends readonly unknown[] = []> implements HavingObserveAbility<GValue, GArguments> {
     #private;
+    /**
+     * Creates a new {@link ObserveAbility}.
+     *
+     * @param observe - The observable async function emitting the observed values.
+     */
     constructor(observe: ObservableAsyncFunction<GValue, GArguments>);
+    /** The wrapped observable async function emitting the observed values over time. */
     get observe(): ObservableAsyncFunction<GValue, GArguments>;
 }

package/src/individual/observe/observe-ability.js

@@ -1,8 +1,29 @@
+/**
+ * The ability to observe values over time, wrapping an {@link ObservableAsyncFunction}.
+ *
+ * @template GValue - The type of the observed values.
+ * @template GArguments - The tuple type of the extra arguments passed at observation time.
+ *
+ * @example
+ * ```ts
+ * const temperature: ObserveAbility<number> = new ObserveAbility(temperatureChanges);
+ *
+ * for await (const value of temperature.observe.values(signal)) {
+ *   console.log(value); // every emitted temperature
+ * }
+ * ```
+ */
 export class ObserveAbility {
     #observe;
+    /**
+     * Creates a new {@link ObserveAbility}.
+     *
+     * @param observe - The observable async function emitting the observed values.
+     */
     constructor(observe) {
         this.#observe = observe;
     }
+    /** The wrapped observable async function emitting the observed values over time. */
     get observe() {
         return this.#observe;
     }

package/src/individual/observe/observe-ability.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe-ability.js","sourceRoot":"","sources":["../../../../src/individual/observe/observe-ability.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,cAAc;IAIhB,QAAQ,CAA8C;IAE/D,YAAY,OAAoD;QAC9D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"observe-ability.js","sourceRoot":"","sources":["../../../../src/individual/observe/observe-ability.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IAIhB,QAAQ,CAA8C;IAE/D;;;;OAIG;IACH,YAAY,OAAoD;QAC9D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,oFAAoF;IACpF,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

package/src/individual/read/having-read-ability.d.ts

@@ -1,4 +1,10 @@
 import type { ReadAction } from './read-action.ts';
+/**
+ * An object having the ability to read: it exposes a {@link ReadAction}.
+ *
+ * @template GValue - The type of the read value.
+ */
 export interface HavingReadAbility<GValue> {
+    /** Reads and returns the current value. */
     readonly read: ReadAction<GValue>;
 }

package/src/individual/read/read-action.d.ts

@@ -1,2 +1,9 @@
 import type { AsyncFunction } from '@xstd/async-function';
+/**
+ * An asynchronous, abortable action that reads and returns a value.
+ *
+ * Calling it resolves with the read value.
+ *
+ * @template GValue - The type of the read value.
+ */
 export type ReadAction<GValue> = AsyncFunction<[], GValue>;

package/src/individual/send/having-send-ability.d.ts

@@ -1,4 +1,10 @@
 import type { SendAction } from './send-action.ts';
+/**
+ * An object having the ability to send: it exposes a {@link SendAction}.
+ *
+ * @template GArguments - The tuple type of the arguments accepted by the send action.
+ */
 export interface HavingSendAbility<GArguments extends readonly unknown[]> {
+    /** Sends (triggers) something with the provided arguments, without expecting any result. */
     readonly send: SendAction<GArguments>;
 }

package/src/individual/send/send-action.d.ts

@@ -1,2 +1,10 @@
 import type { AsyncFunction } from '@xstd/async-function';
+/**
+ * An asynchronous, abortable action that sends (triggers) something with the provided arguments,
+ * without expecting any result.
+ *
+ * Calling it resolves with `void` once the action is completed.
+ *
+ * @template GArguments - The tuple type of the arguments passed to the action.
+ */
 export type SendAction<GArguments extends readonly unknown[]> = AsyncFunction<GArguments, void>;

package/src/individual/write/having-write-ability.d.ts

@@ -1,4 +1,10 @@
 import type { WriteAction } from './write-action.ts';
+/**
+ * An object having the ability to write: it exposes a {@link WriteAction}.
+ *
+ * @template GValue - The type of the writable value.
+ */
 export interface HavingWriteAbility<GValue> {
+    /** Writes the provided value. */
     readonly write: WriteAction<GValue>;
 }

package/src/individual/write/write-action.d.ts

@@ -1,2 +1,9 @@
 import type { AsyncFunction } from '@xstd/async-function';
+/**
+ * An asynchronous, abortable action that writes a value, without expecting any result.
+ *
+ * Calling it resolves with `void` once the value was written.
+ *
+ * @template GValue - The type of the written value.
+ */
 export type WriteAction<GValue> = AsyncFunction<[GValue], void>;