deprecation(uuid): deprecate v1.generate() signature with buf and offset parameters (#4880)

uuid/v1.ts

@@ -103,7 +103,41 @@ export interface GenerateOptions {
  * const uuid = generate(options) as string;
  * assert(validate(uuid));
  * ```
+ *
+ * @deprecated This will be removed in 1.0.0. Use the other overload instead.
  */
+export function generate(
+  options?: GenerateOptions,
+  buf?: number[],
+  offset?: number,
+): string | number[];
+/**
+ * Generates a
+ * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.1 | UUIDv1}.
+ *
+ * @param options Can use RFC time sequence values as overwrites.
+ * @param buf Can allow the UUID to be written in byte-form starting at the offset.
+ * @param offset Index to start writing on the UUID bytes in buffer.
+ *
+ * @returns Returns a UUIDv1 string or an array of 16 bytes.
+ *
+ * @example Usage
+ * ```ts
+ * import { generate, validate } from "@std/uuid/v1";
+ * import { assert } from "@std/assert/assert";
+ *
+ * const options = {
+ *   node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
+ *   clockseq: 0x1234,
+ *   msecs: new Date("2011-11-01").getTime(),
+ *   nsecs: 5678,
+ * };
+ *
+ * const uuid = generate(options) as string;
+ * assert(validate(uuid));
+ * ```
+ */
+export function generate(options?: GenerateOptions): string;
 export function generate(
   options: GenerateOptions = {},
   buf?: number[],