@fluidframework/counter 1.2.7 → 2.0.0-dev.1.3.0.96595

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/counter",
-  "version": "1.2.7",
+  "version": "2.0.0-dev.1.3.0.96595",
   "description": "Counter DDS",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -58,27 +58,27 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluidframework/common-utils": "^0.32.1",
-    "@fluidframework/core-interfaces": "^1.2.7",
-    "@fluidframework/datastore-definitions": "^1.2.7",
-    "@fluidframework/driver-utils": "^1.2.7",
-    "@fluidframework/protocol-definitions": "^0.1028.2000",
-    "@fluidframework/runtime-definitions": "^1.2.7",
-    "@fluidframework/shared-object-base": "^1.2.7"
+    "@fluidframework/common-utils": "^1.0.0",
+    "@fluidframework/core-interfaces": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/datastore-definitions": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/driver-utils": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/protocol-definitions": "^1.0.0",
+    "@fluidframework/runtime-definitions": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/shared-object-base": "2.0.0-dev.1.3.0.96595"
   },
   "devDependencies": {
-    "@fluidframework/build-common": "^0.24.0",
-    "@fluidframework/build-tools": "^0.2.74327",
-    "@fluidframework/counter-previous": "npm:@fluidframework/counter@1.2.1",
-    "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/mocha-test-setup": "^1.2.7",
-    "@fluidframework/test-runtime-utils": "^1.2.7",
+    "@fluidframework/build-common": "^1.0.0",
+    "@fluidframework/build-tools": "^0.4.6000",
+    "@fluidframework/counter-previous": "npm:@fluidframework/counter@^1.0.0",
+    "@fluidframework/eslint-config-fluid": "^1.0.0",
+    "@fluidframework/mocha-test-setup": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/test-runtime-utils": "2.0.0-dev.1.3.0.96595",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/mocha": "^9.1.1",
     "@types/node": "^14.18.0",
     "concurrently": "^6.2.0",
-    "copyfiles": "^2.1.0",
+    "copyfiles": "^2.4.1",
     "cross-env": "^7.0.2",
     "eslint": "~8.6.0",
     "mocha": "^10.0.0",
@@ -87,7 +87,7 @@
     "typescript": "~4.5.5"
   },
   "typeValidation": {
-    "version": "1.2.2",
+    "version": "2.0.0",
     "broken": {}
   }
 }

package/src/counter.ts

@@ -17,7 +17,7 @@ import { CounterFactory } from "./counterFactory";
 import { ISharedCounter, ISharedCounterEvents } from "./interfaces";
 
 /**
- * Describes the op format for incrementing the counter
+ * Describes the operation (op) format for incrementing the {@link SharedCounter}.
  */
 interface IIncrementOperation {
     type: "increment";
@@ -25,55 +25,67 @@ interface IIncrementOperation {
 }
 
 /**
- * Used in snapshotting.
+ * @remarks Used in snapshotting.
  */
 interface ICounterSnapshotFormat {
-    // The value of the counter
+    /**
+     * The value of the counter.
+     */
     value: number;
 }
 
 const snapshotFileName = "header";
 
 /**
- * A `SharedCounter` is a shared object which holds a number that can be incremented or decremented.
- * @public
+ * A shared object that holds a number that can be incremented or decremented.
+ *
+ * @remarks Note that `SharedCounter` only operates on integer values. This is validated at runtime.
  *
- * @remarks
- * ### Creation
+ * @example Creating a `SharedCounter`:
  *
- * To create a `SharedCounter`, get the factory and call create with a runtime and string ID:
+ * First, get the factory and call {@link @fluidframework/datastore-definitions#IChannelFactory.create}
+ * with a runtime and string ID:
  *
  * ```typescript
  * const factory = SharedCounter.getFactory();
  * const counter = factory.create(this.runtime, id) as SharedCounter;
  * ```
  *
- * ### Usage
+ * The initial value of a new `SharedCounter` is 0.
+ * If you wish to initialize the counter to a different value, you may call {@link SharedCounter.increment} before
+ * attaching the Container, or before inserting it into an existing shared object.
  *
- * Once created, you can call `increment` to modify the value with either a positive or negative number:
+ * @example Using the `SharedCounter`:
+ *
+ * Once created, you can call {@link SharedCounter.increment} to modify the value with either a positive or
+ * negative number:
  *
  * ```typescript
  * counter.increment(10); // add 10 to the counter value
  * counter.increment(-5); // subtract 5 from the counter value
  * ```
  *
- * To observe changes to the value (including those from remote clients), register for the `"incremented"` event:
+ * To observe changes to the value (including those from remote clients), register for the
+ * {@link ISharedCounterEvents | incremented} event:
  *
  * ```typescript
  * counter.on("incremented", (incrementAmount, newValue) => {
  *     console.log(`The counter incremented by ${incrementAmount} and now has a value of ${newValue}`);
  * });
  * ```
+ *
+ * @public
  */
 export class SharedCounter extends SharedObject<ISharedCounterEvents> implements ISharedCounter {
     /**
-     * Create a new shared counter
+     * Create a new {@link SharedCounter}.
+     *
+     * @param runtime - The data store runtime to which the new `SharedCounter` will belong.
+     * @param id - Optional name of the `SharedCounter`. If not provided, one will be generated.
      *
-     * @param runtime - data store runtime the new shared counter belongs to
-     * @param id - optional name of the shared counter
      * @returns newly create shared counter (but not attached yet)
      */
-    public static create(runtime: IFluidDataStoreRuntime, id?: string) {
+    public static create(runtime: IFluidDataStoreRuntime, id?: string): SharedCounter {
         return runtime.createChannel(id, CounterFactory.Type) as SharedCounter;
     }
 
@@ -82,7 +94,7 @@ export class SharedCounter extends SharedObject<ISharedCounterEvents> implements
     }
 
     /**
-     * Get a factory for SharedCounter to register with the data store.
+     * Get a factory for {@link SharedCounter} to register with the data store.
      *
      * @returns a factory that creates and load SharedCounter
      */
@@ -95,14 +107,14 @@ export class SharedCounter extends SharedObject<ISharedCounterEvents> implements
     /**
      * {@inheritDoc ISharedCounter.value}
      */
-    public get value() {
+    public get value(): number {
         return this._value;
     }
 
     /**
      * {@inheritDoc ISharedCounter.increment}
      */
-    public increment(incrementAmount: number) {
+    public increment(incrementAmount: number): void {
         // Incrementing by floating point numbers will be eventually inconsistent, since the order in which the
         // increments are applied affects the result.  A more-robust solution would be required to support this.
         if (incrementAmount % 1 !== 0) {
@@ -118,15 +130,16 @@ export class SharedCounter extends SharedObject<ISharedCounterEvents> implements
         this.submitLocalMessage(op);
     }
 
-    private incrementCore(incrementAmount: number) {
+    private incrementCore(incrementAmount: number): void {
         this._value += incrementAmount;
         this.emit("incremented", incrementAmount, this._value);
     }
 
     /**
-     * Create a summary for the counter
+     * Create a summary for the counter.
+     *
+     * @returns The summary of the current state of the counter.
      *
-     * @returns the summary of the current state of the counter
      * @internal
      */
     protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats {
@@ -141,6 +154,7 @@ export class SharedCounter extends SharedObject<ISharedCounterEvents> implements
 
     /**
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
+     *
      * @internal
      */
     protected async loadCore(storage: IChannelStorageService): Promise<void> {
@@ -151,20 +165,22 @@ export class SharedCounter extends SharedObject<ISharedCounterEvents> implements
 
     /**
      * Called when the object has disconnected from the delta stream.
+     *
      * @internal
      */
-    protected onDisconnect() { }
+    protected onDisconnect(): void { }
 
     /**
-     * Process a counter operation
+     * Process a counter operation (op).
      *
-     * @param message - the message to prepare
-     * @param local - whether the message was sent by the local client
+     * @param message - The message to prepare.
+     * @param local - Whether or not the message was sent by the local client.
      * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
-     * For messages from a remote client, this will be undefined.
+     * For messages from a remote client, this will be `undefined`.
+     *
      * @internal
      */
-    protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown) {
+    protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void {
         if (message.type === MessageType.Operation && !local) {
             const op = message.contents as IIncrementOperation;
 
@@ -181,9 +197,10 @@ export class SharedCounter extends SharedObject<ISharedCounterEvents> implements
 
     /**
      * Not implemented.
+     *
      * @internal
      */
     protected applyStashedOp() {
-        throw new Error("not implemented");
+        throw new Error("Not implemented");
     }
 }

package/src/counterFactory.ts

@@ -14,22 +14,36 @@ import { ISharedCounter } from "./interfaces";
 import { pkgVersion } from "./packageVersion";
 
 /**
- * The factory that defines the counter
+ * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedCounter}.
+ *
+ * @sealed
  */
 export class CounterFactory implements IChannelFactory {
+    /**
+     * Static value for {@link CounterFactory."type"}.
+     */
     public static readonly Type = "https://graph.microsoft.com/types/counter";
 
+    /**
+     * Static value for {@link CounterFactory.attributes}.
+     */
     public static readonly Attributes: IChannelAttributes = {
         type: CounterFactory.Type,
         snapshotFormatVersion: "0.1",
         packageVersion: pkgVersion,
     };
 
-    public get type() {
+    /**
+     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
+     */
+    public get type(): string {
         return CounterFactory.Type;
     }
 
-    public get attributes() {
+    /**
+     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
+     */
+    public get attributes(): IChannelAttributes {
         return CounterFactory.Attributes;
     }
 
@@ -46,6 +60,9 @@ export class CounterFactory implements IChannelFactory {
         return counter;
     }
 
+    /**
+     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
+     */
     public create(document: IFluidDataStoreRuntime, id: string): ISharedCounter {
         const counter = new SharedCounter(id, document, this.attributes);
         counter.initializeLocal();

package/src/index.ts

@@ -4,8 +4,8 @@
  */
 
 /**
- * This package contains the SharedCounter distributed data structure. A SharedCounter is a shared object
- * which holds a number that can be incremented or decremented.
+ * This library contains the {@link SharedCounter} distributed data structure.
+ * A `SharedCounter` is a shared object which holds a whole number that can be incremented or decremented.
  *
  * @packageDocumentation
  */

package/src/interfaces.ts

@@ -6,7 +6,8 @@
 import { ISharedObject, ISharedObjectEvents } from "@fluidframework/shared-object-base";
 
 /**
- * Events sent by SharedCounters.
+ * Events sent by {@link SharedCounter}.
+ *
  * @public
  */
 export interface ISharedCounterEvents extends ISharedObjectEvents {
@@ -22,19 +23,23 @@ export interface ISharedCounterEvents extends ISharedObjectEvents {
 }
 
 /**
- * SharedCounter interface.
+ * {@link SharedCounter} interface.
+ *
  * @public
  */
 export interface ISharedCounter extends ISharedObject<ISharedCounterEvents> {
     /**
      * The counter value.
+     *
+     * @remarks Must be a whole number.
      */
     value: number;
 
     /**
-     * Increments or decrements the value.  Must only increment or decrement by a whole number value.
+     * Increments or decrements the value.
+     * Must only increment or decrement by a whole number value.
      *
-     * @param incrementAmount - a whole number to increment or decrement by.
+     * @param incrementAmount - A whole number to increment or decrement by.
      */
     increment(incrementAmount: number): void;
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/counter";
-export const pkgVersion = "1.2.7";
+export const pkgVersion = "2.0.0-dev.1.3.0.96595";