@snaptrude/plugin-core 0.2.4 → 0.2.6

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
+ */
+export type ComponentId = string;
+/**
+ * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
+ */
+export type PluginApiReturn<T> = Promise<T> | T;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/entity/space.ts

@@ -266,6 +266,112 @@ export abstract class PluginSpaceApi {
   public abstract update(
     args: PluginSpaceUpdateArgs,
   ): PluginApiReturn<PluginSpaceUpdateResult>
+
+  /**
+   * Create many spaces in a single undoable operation.
+   *
+   * Each item is either a rectangular box (`kind: "rectangular"`) or an
+   * extruded profile (`kind: "profile"`), and may optionally set `room_type`,
+   * `spaceType`, `massType`, and `departmentId`. All creations — and the
+   * optional property assignments — are batched into **one** command, so the
+   * entire batch is undone/redone in a single step.
+   *
+   * All items are validated first; if any item is invalid the call **throws**
+   * and no spaces are created (nothing is applied) — consistent with the
+   * single-item create methods.
+   *
+   * @param args - {@linkcode PluginSpaceBulkCreateArgs} with an `items` array
+   * @returns A {@linkcode PluginSpaceBulkCreateResult} with the `spaceIds` of
+   *   the created spaces, in input order
+   * @throws If any item has invalid dimensions, height, or profile
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const { spaceIds } = await snaptrude.entity.space.bulkCreate({
+   *   items: [
+   *     {
+   *       kind: "rectangular",
+   *       position: vec3.new(0, 0, 0),
+   *       dimensions: { width: 5, height: 3, depth: 4 },
+   *       spaceType: "Room",
+   *       departmentId: "CORE",
+   *     },
+   *     {
+   *       kind: "profile",
+   *       profile: await snaptrude.core.geom.profile.fromLinePoints({
+   *         points: [vec3.new(0, 0, 0), vec3.new(8, 0, 0), vec3.new(8, 0, 6), vec3.new(0, 0, 6)],
+   *       }),
+   *       extrudeHeight: 3,
+   *       position: vec3.new(10, 0, 0),
+   *       massType: "Room",
+   *     },
+   *   ],
+   * })
+   * ```
+   */
+  public abstract bulkCreate(
+    args: PluginSpaceBulkCreateArgs,
+  ): PluginApiReturn<PluginSpaceBulkCreateResult>
+
+  /**
+   * Update many existing spaces in a single undoable operation.
+   *
+   * Each item targets an existing space by `spaceId` and may change its
+   * geometry (`profile` + `extrudeHeight`, which must be supplied together) and/or
+   * its `properties` (`room_type`, `massType`, `spaceType`, `departmentId` —
+   * nested under `properties`, mirroring {@linkcode PluginSpaceApi.update}). All
+   * changes are batched into **one** command, so the entire batch is
+   * undone/redone in a single step.
+   *
+   * All items are validated first; if any item is invalid — an unknown
+   * `spaceId`, a non-positive height, or supplying only one of
+   * `profile`/`extrudeHeight` — the call **throws** and no changes are applied.
+   *
+   * @param args - {@linkcode PluginSpaceBulkUpdateArgs} with an `items` array
+   * @returns A {@linkcode PluginSpaceBulkUpdateResult} echoing one
+   *   {@linkcode PluginSpaceUpdateResult} per item in `spaces`, in input order
+   * @throws If any item targets an unknown space, has a non-positive height, or
+   *   supplies only one of `profile`/`extrudeHeight`
+   *
+   * # Example
+   * ```ts
+   * const { spaces } = await snaptrude.entity.space.bulkUpdate({
+   *   items: [
+   *     { spaceId: "space-a", properties: { room_type: "Kitchen", spaceType: "Room" } },
+   *     { spaceId: "space-b", profile, extrudeHeight: 4 },
+   *   ],
+   * })
+   * ```
+   */
+  public abstract bulkUpdate(
+    args: PluginSpaceBulkUpdateArgs,
+  ): PluginApiReturn<PluginSpaceBulkUpdateResult>
+
+  /**
+   * Delete many spaces in a single undoable operation.
+   *
+   * All deletions are batched into **one** command, so the entire batch is
+   * undone/redone in a single step.
+   *
+   * All IDs are validated first; if any ID is unknown or is not a space the
+   * call **throws** and no spaces are deleted — consistent with the single-item
+   * {@linkcode PluginSpaceApi.delete}.
+   *
+   * @param args - {@linkcode PluginSpaceBulkDeleteArgs} with a `spaceIds` array
+   * @returns A {@linkcode PluginSpaceBulkDeleteResult} with `deletedSpaceIds`
+   *   (the removed IDs, in input order)
+   * @throws If any ID does not resolve to an existing space
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.entity.space.bulkDelete({ spaceIds: ["space-a", "space-b"] })
+   * ```
+   */
+  public abstract bulkDelete(
+    args: PluginSpaceBulkDeleteArgs,
+  ): PluginApiReturn<PluginSpaceBulkDeleteResult>
 }
 
 /**
@@ -659,3 +765,167 @@ export const PluginSpaceUpdateResult = z.object({
 })
 
 export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>
+
+// ---------------------------------------------------------------------------
+// Bulk operations
+// ---------------------------------------------------------------------------
+
+/**
+ * A single item for {@linkcode PluginSpaceApi.bulkCreate}.
+ *
+ * Discriminated on `kind`:
+ * - `"rectangular"` — a box defined by `position` + `dimensions` (mirrors
+ *   {@linkcode PluginSpaceCreateRectangularArgs})
+ * - `"profile"` — an extruded `profile` (with optional `innerProfiles`) by
+ *   `extrudeHeight` at `position` (mirrors {@linkcode PluginSpaceCreateFromProfileArgs})
+ *
+ * Every item may optionally set `room_type`, `spaceType`, `massType`, and
+ * `departmentId`; these are applied within the same single undo step as the
+ * creation.
+ */
+export const PluginSpaceBulkCreateItem = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("rectangular"),
+    position: PVec3,
+    dimensions: z.object({
+      width: z.number(),
+      height: z.number(),
+      depth: z.number(),
+    }),
+    room_type: z.string().optional(),
+    spaceType: PluginSpaceType.optional(),
+    massType: PluginMassType.optional(),
+    departmentId: PluginDepartmentId.optional(),
+  }),
+  z.object({
+    kind: z.literal("profile"),
+    profile: PProfile,
+    innerProfiles: z.array(PProfile).optional(),
+    extrudeHeight: z.number(),
+    position: PVec3,
+    room_type: z.string().optional(),
+    spaceType: PluginSpaceType.optional(),
+    massType: PluginMassType.optional(),
+    departmentId: PluginDepartmentId.optional(),
+  }),
+])
+
+export type PluginSpaceBulkCreateItem = z.infer<typeof PluginSpaceBulkCreateItem>
+
+/**
+ * Arguments for {@linkcode PluginSpaceApi.bulkCreate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `items` | {@linkcode PluginSpaceBulkCreateItem}`[]` | Spaces to create |
+ */
+export const PluginSpaceBulkCreateArgs = z.object({
+  items: z.array(PluginSpaceBulkCreateItem),
+})
+
+export type PluginSpaceBulkCreateArgs = z.infer<typeof PluginSpaceBulkCreateArgs>
+
+/**
+ * Result of {@linkcode PluginSpaceApi.bulkCreate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `string[]` | IDs of the created spaces, in input order |
+ */
+export const PluginSpaceBulkCreateResult = z.object({
+  spaceIds: z.array(z.string()),
+})
+
+export type PluginSpaceBulkCreateResult = z.infer<
+  typeof PluginSpaceBulkCreateResult
+>
+
+/**
+ * A single item for {@linkcode PluginSpaceApi.bulkUpdate}.
+ *
+ * Targets an existing space by `spaceId`. Geometry fields `profile` and
+ * `extrudeHeight` must be supplied **together** (mirrors
+ * {@linkcode PluginSpaceUpdateGeometryFromProfileArgs}). Property changes are
+ * nested under `properties`, mirroring {@linkcode PluginSpaceUpdateArgs}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space to update |
+ * | `profile` | {@linkcode PProfile}`?` | New floor shape (requires `extrudeHeight`) |
+ * | `extrudeHeight` | `number?` | New extrusion height (requires `profile`) |
+ * | `properties` | `object?` | Property changes (same shape as {@linkcode PluginSpaceUpdateArgs.properties}) |
+ */
+export const PluginSpaceBulkUpdateItem = z.object({
+  spaceId: z.string(),
+  profile: PProfile.optional(),
+  extrudeHeight: z.number().optional(),
+  properties: z
+    .object({
+      room_type: z.string().optional(),
+      massType: PluginMassType.optional(),
+      spaceType: PluginSpaceType.optional(),
+      departmentId: PluginDepartmentId.optional(),
+    })
+    .optional(),
+})
+
+export type PluginSpaceBulkUpdateItem = z.infer<typeof PluginSpaceBulkUpdateItem>
+
+/**
+ * Arguments for {@linkcode PluginSpaceApi.bulkUpdate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `items` | {@linkcode PluginSpaceBulkUpdateItem}`[]` | Spaces to update |
+ */
+export const PluginSpaceBulkUpdateArgs = z.object({
+  items: z.array(PluginSpaceBulkUpdateItem),
+})
+
+export type PluginSpaceBulkUpdateArgs = z.infer<typeof PluginSpaceBulkUpdateArgs>
+
+/**
+ * Result of {@linkcode PluginSpaceApi.bulkUpdate}.
+ *
+ * Echoes one {@linkcode PluginSpaceUpdateResult} per item, in input order —
+ * the same per-space shape returned by {@linkcode PluginSpaceApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaces` | {@linkcode PluginSpaceUpdateResult}`[]` | Per-item updated values, in input order |
+ */
+export const PluginSpaceBulkUpdateResult = z.object({
+  spaces: z.array(PluginSpaceUpdateResult),
+})
+
+export type PluginSpaceBulkUpdateResult = z.infer<
+  typeof PluginSpaceBulkUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginSpaceApi.bulkDelete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `string[]` | The space IDs to delete |
+ */
+export const PluginSpaceBulkDeleteArgs = z.object({
+  spaceIds: z.array(z.string()),
+})
+
+export type PluginSpaceBulkDeleteArgs = z.infer<typeof PluginSpaceBulkDeleteArgs>
+
+/**
+ * Result of {@linkcode PluginSpaceApi.bulkDelete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deletedSpaceIds` | `string[]` | The space IDs that were removed |
+ */
+export const PluginSpaceBulkDeleteResult = z.object({
+  deletedSpaceIds: z.array(z.string()),
+})
+
+export type PluginSpaceBulkDeleteResult = z.infer<
+  typeof PluginSpaceBulkDeleteResult
+>