@highstate/library 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/library",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "highstate": {
     "type": "library"
@@ -25,13 +25,13 @@
   },
   "dependencies": {
     "remeda": "^2.21.0",
-    "@highstate/contract": "0.18.0"
+    "@highstate/contract": "0.20.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.0",
     "@typescript/native-preview": "^7.0.0-dev.20250920.1",
     "type-fest": "^4.41.0",
-    "@highstate/cli": "0.18.0"
+    "@highstate/cli": "0.20.0"
   },
   "repository": {
     "url": "https://github.com/highstate-io/highstate"

package/src/abbreviations.ts

@@ -28,9 +28,12 @@ registerKnownAbbreviations([
   "CNI",
   "CSI",
   "MariaDB",
+  "MySQL",
   "PostgreSQL",
   "MongoDB",
   "etcd",
+  "MAS", // Matrix Authentication Service
+  "LC", // Locale
 ])
 
 export const noop = () => {}

package/src/common/access-point.ts

@@ -1,4 +1,10 @@
-import { defineEntity, defineUnit, z } from "@highstate/contract"
+import {
+  defineEntity,
+  defineUnit,
+  type EntityInput,
+  type EntityValue,
+  z,
+} from "@highstate/contract"
 import * as dns from "../dns"
 import { implementationReferenceSchema } from "../impl-ref"
 import { l3EndpointEntity } from "../network"
@@ -21,6 +27,9 @@ export const gatewayEntity = defineEntity({
   }),
 
   meta: {
+    title: "Gateway",
+    icon: "mdi:router-network",
+    iconColor: "#F57F17",
     color: "#F57F17",
   },
 })
@@ -41,6 +50,9 @@ export const tlsIssuerEntity = defineEntity({
   }),
 
   meta: {
+    title: "TLS Issuer",
+    icon: "mdi:certificate-outline",
+    iconColor: "#F57F17",
     color: "#F57F17",
   },
 })
@@ -71,6 +83,9 @@ export const accessPointEntity = defineEntity({
   }),
 
   meta: {
+    title: "Access Point",
+    icon: "mdi:access-point",
+    iconColor: "#F57F17",
     color: "#F57F17",
   },
 })
@@ -125,6 +140,10 @@ export const accessPoint = defineUnit({
   },
 })
 
-export type Gateway = z.infer<typeof gatewayEntity.schema>
-export type AccessPoint = z.infer<typeof accessPointEntity.schema>
-export type TlsIssuer = z.infer<typeof tlsIssuerEntity.schema>
+export type Gateway = EntityValue<typeof gatewayEntity>
+export type AccessPoint = EntityValue<typeof accessPointEntity>
+export type TlsIssuer = EntityValue<typeof tlsIssuerEntity>
+
+export type GatewayInput = EntityInput<typeof gatewayEntity>
+export type AccessPointInput = EntityInput<typeof accessPointEntity>
+export type TlsIssuerInput = EntityInput<typeof tlsIssuerEntity>

package/src/common/files.ts

@@ -4,6 +4,8 @@ import {
   fileMetaSchema as baseFileMetaSchema,
   defineEntity,
   defineUnit,
+  type EntityInput,
+  type EntityValue,
   unitArtifactSchema,
   z,
 } from "@highstate/contract"
@@ -18,10 +20,6 @@ export const checksumSchema = z.object({
 
 export const fileContentSchema = z.union([
   baseFileContentSchema,
-  z.object({
-    type: z.literal("local"),
-    path: z.string(),
-  }),
   z.object({
     type: z.literal("remote"),
     endpoint: l7EndpointEntity.schema,
@@ -38,7 +36,10 @@ export const fileEntity = defineEntity({
   }),
 
   meta: {
-    color: "#FF5722",
+    title: "File",
+    icon: "mdi:file",
+    iconColor: "#2196F3",
+    color: "#2196F3",
   },
 })
 
@@ -50,15 +51,6 @@ export const folderMetaSchema = z.object({
 export const folderContentSchema = z.union([
   z.object({
     type: z.literal("embedded"),
-    files: fileEntity.schema.array(),
-    folders: z
-      .object({
-        meta: folderMetaSchema,
-        get content() {
-          return folderContentSchema
-        },
-      })
-      .array(),
   }),
   z.object({
     type: z.literal("artifact"),
@@ -77,13 +69,29 @@ export const folderContentSchema = z.union([
 export const folderEntity = defineEntity({
   type: "common.folder.v1",
 
+  includes: {
+    files: {
+      entity: fileEntity,
+      multiple: true,
+      required: false,
+    },
+    folders: {
+      entity: () => folderEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
   schema: z.object({
     meta: folderMetaSchema,
     content: folderContentSchema,
   }),
 
   meta: {
-    color: "#FF9800",
+    title: "Folder",
+    icon: "mdi:folder",
+    iconColor: "#4CAF50",
+    color: "#4CAF50",
   },
 })
 
@@ -136,7 +144,8 @@ export const remoteFile = defineUnit({
   },
 })
 
-export type File = z.infer<typeof fileEntity.schema>
+export type File = EntityValue<typeof fileEntity>
+export type FileInput = EntityInput<typeof fileEntity>
 export type FileMeta = z.infer<typeof baseFileMetaSchema>
 export type FileContent = z.infer<typeof fileContentSchema>
 
@@ -145,7 +154,8 @@ export type ArtifactFile = Simplify<File & { content: { type: "artifact" } }>
 export type LocalFile = Simplify<File & { content: { type: "local" } }>
 export type RemoteFile = Simplify<File & { content: { type: "remote" } }>
 
-export type Folder = z.infer<typeof folderEntity.schema>
+export type Folder = EntityValue<typeof folderEntity>
+export type FolderInput = EntityInput<typeof folderEntity>
 export type FolderMeta = z.infer<typeof folderMetaSchema>
 export type FolderContent = z.infer<typeof folderContentSchema>
 

package/src/common/server.ts

@@ -1,5 +1,13 @@
-import { $outputs, $secrets, defineEntity, defineUnit, z } from "@highstate/contract"
-import { l3EndpointEntity } from "../network"
+import {
+  $outputs,
+  $secrets,
+  defineEntity,
+  defineUnit,
+  type EntityInput,
+  type EntityValue,
+  z,
+} from "@highstate/contract"
+import { l3EndpointContainer, l3EndpointEntity } from "../network"
 import * as ssh from "../ssh"
 
 /**
@@ -12,20 +20,32 @@ import * as ssh from "../ssh"
 export const serverEntity = defineEntity({
   type: "common.server.v1",
 
+  extends: { l3EndpointContainer },
+
   includes: {
-    endpoints: {
-      entity: l3EndpointEntity,
-      multiple: true,
+    /**
+     * The SSH configuration for the server.
+     *
+     * If not specified, it will be assumed that the server is not accessible via SSH.
+     */
+    ssh: {
+      entity: ssh.connectionEntity,
+      required: false,
     },
   },
 
   schema: z.object({
+    /**
+     * The hostname of the server.
+     */
     hostname: z.string(),
-    ssh: ssh.connectionSchema.optional(),
   }),
 
   meta: {
     color: "#009688",
+    title: "Server",
+    icon: "mdi:server",
+    iconColor: "#009688",
   },
 })
 
@@ -186,4 +206,5 @@ export const script = defineUnit({
   },
 })
 
-export type Server = z.infer<typeof serverEntity.schema>
+export type Server = EntityValue<typeof serverEntity>
+export type ServerInput = EntityInput<typeof serverEntity>

package/src/databases/etcd.ts

@@ -1,27 +1,57 @@
-import { defineEntity, defineUnit, z } from "@highstate/contract"
-import { l4EndpointEntity } from "../network"
-import { toPatchArgs } from "../utils"
+import {
+  defineEntity,
+  defineUnit,
+  type EntityInput,
+  type EntityValue,
+  secretSchema,
+  z,
+} from "@highstate/contract"
+import { l4EndpointContainer, l4EndpointEntity } from "../network"
+import { certificateEntity } from "../tls"
 
-const etcdArgs = {
-  endpoints: {
-    schema: z.string().array().default([]),
-  },
-}
+/**
+ * The credentials for authenticating to the etcd cluster.
+ */
+export const credentialsSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("password"),
+
+    /**
+     * The username used to authenticate against the database.
+     */
+    username: z.string(),
+
+    /**
+     * The password used to authenticate against the database.
+     */
+    password: secretSchema(z.string()),
+  }),
+])
 
 /**
- * Represents the etcd database instance.
+ * Represents a connection to the etcd cluster.
  */
-export const etcdEntity = defineEntity({
-  type: "databases.etcd.v1",
+export const connectionEntity = defineEntity({
+  type: "etcd.connection.v1",
+
+  extends: { l4EndpointContainer },
 
   includes: {
-    endpoints: {
-      entity: l4EndpointEntity,
-      multiple: true,
+    /**
+     * The TLS certificate of the server if any.
+     */
+    certificate: {
+      entity: certificateEntity,
+      required: false,
     },
   },
 
-  schema: z.unknown(),
+  schema: z.object({
+    /**
+     * The credentials for authenticating to the etcd cluster.
+     */
+    credentials: credentialsSchema.optional(),
+  }),
 
   meta: {
     color: "#0064bf",
@@ -29,14 +59,34 @@ export const etcdEntity = defineEntity({
 })
 
 /**
- * The existing etcd database instance.
+ * The connection to an existing etcd cluster hosted on a server or a managed service.
  */
-export const existingEtcd = defineUnit({
-  type: "databases.etcd.existing.v1",
+export const connection = defineUnit({
+  type: "etcd.connection.v1",
+
+  args: {
+    /**
+     * The endpoints to connect to the etcd cluster.
+     */
+    endpoints: z.string().array().default([]),
+
+    /**
+     * The username to authenticate with.
+     */
+    username: z.string().optional(),
+  },
 
-  args: etcdArgs,
+  secrets: {
+    /**
+     * The password to authenticate with.
+     */
+    password: z.string().optional(),
+  },
 
   inputs: {
+    /**
+     * The endpoints to connect to the etcd cluster.
+     */
     endpoints: {
       entity: l4EndpointEntity,
       multiple: true,
@@ -45,12 +95,12 @@ export const existingEtcd = defineUnit({
   },
 
   outputs: {
-    etcd: etcdEntity,
+    connection: connectionEntity,
   },
 
   source: {
-    package: "@highstate/common",
-    path: "units/databases/existing-etcd",
+    package: "@highstate/etcd",
+    path: "units/connection",
   },
 
   meta: {
@@ -61,37 +111,92 @@ export const existingEtcd = defineUnit({
   },
 })
 
+export const namespacePermissionSchema = z.object({
+  /**
+   * The prefix of the namespace to grant access to.
+   */
+  prefix: z.string(),
+
+  /**
+   * The range end of the namespace to grant access to.
+   *
+   * If not specified, all keys with the given prefix will be included in the namespace.
+   */
+  rangeEnd: z.string().optional(),
+
+  /**
+   * The access level to grant to the namespace.
+   *
+   * If not specified, defaults to `readwrite`.
+   */
+  permission: z.enum(["read", "write", "readwrite"]).default("readwrite"),
+})
+
 /**
- * Patches some properties of the etcd database and outputs the updated database.
+ * The namespace within an existing etcd cluster.
  */
-export const etcdPatch = defineUnit({
-  type: "databases.etcd-patch.v1",
+export const namespace = defineUnit({
+  type: "etcd.namespace.v1",
+
+  args: {
+    /**
+     * The name of the role to define for the namespace.
+     *
+     * If not provided, the name of the unit will be used.
+     */
+    roleName: z.string().optional(),
+
+    /**
+     * The username of the user to create for the namespace.
+     *
+     * If not provided, the name of the role will be used.
+     */
+    username: z.string().optional(),
+
+    /**
+     * The permissions to grant to the namespace.
+     */
+    permissions: namespacePermissionSchema.array(),
+  },
 
-  args: toPatchArgs(etcdArgs),
+  secrets: {
+    /**
+     * The password of the user to create for the namespace.
+     *
+     * If not provided, a random password will be generated.
+     */
+    password: z.string().optional(),
+  },
 
   inputs: {
-    etcd: etcdEntity,
-
-    endpoints: {
-      entity: l4EndpointEntity,
-      multiple: true,
-      required: false,
+    /**
+     * The connection to the etcd cluster.
+     */
+    connection: {
+      entity: connectionEntity,
+      required: true,
     },
   },
 
   outputs: {
-    etcd: etcdEntity,
+    connection: connectionEntity,
   },
 
   source: {
-    package: "@highstate/common",
-    path: "units/databases/etcd-patch",
+    package: "@highstate/etcd",
+    path: "units/namespace",
   },
 
   meta: {
-    title: "etcd Patch",
+    title: "etcd Namespace",
     icon: "simple-icons:etcd",
-    secondaryIcon: "fluent:patch-20-filled",
+    iconColor: "#0069ab",
+    secondaryIcon: "mdi:database",
     category: "Databases",
   },
 })
+
+export type Credentials = z.infer<typeof credentialsSchema>
+
+export type Connection = EntityValue<typeof connectionEntity>
+export type ConnectionInput = EntityInput<typeof connectionEntity>

package/src/databases/index.ts

@@ -1,7 +1,8 @@
-export * from "./etcd"
-export * from "./mariadb"
-export * from "./mongodb"
-export * from "./postgresql"
-export * from "./redis"
-export * from "./s3"
-export * from "./shared"
+export * as etcd from "./etcd"
+export * as influxdb3 from "./influxdb3"
+export * as minio from "./minio"
+export * as mongodb from "./mongodb"
+export * as mysql from "./mysql"
+export * as postgresql from "./postgresql"
+export * as redis from "./redis"
+export * as s3 from "./s3"

package/src/databases/influxdb3.ts

@@ -0,0 +1,103 @@
+import {
+  defineEntity,
+  defineUnit,
+  type EntityInput,
+  type EntityValue,
+  secretSchema,
+  z,
+} from "@highstate/contract"
+import { l7EndpointContainer } from "../network"
+
+export const credentialsSchema = z.object({
+  /**
+   * The token for authenticating to the InfluxDB 3 instance.
+   */
+  token: secretSchema(z.string()),
+})
+
+/**
+ * Represents a connection to a InfluxDB 3 instance, including the endpoints and credentials.
+ */
+export const connectionEntity = defineEntity({
+  type: "influxdb3.connection.v1",
+
+  extends: { l7EndpointContainer },
+
+  schema: z.object({
+    /**
+     * The credentials for authenticating to the InfluxDB 3 instance.
+     */
+    credentials: credentialsSchema,
+  }),
+
+  meta: {
+    color: "#22adf6",
+  },
+})
+
+/**
+ * Represents an InfluxDB 3 database with credentials and endpoints to access it.
+ */
+export const databaseEntity = defineEntity({
+  type: "influxdb3.database.v1",
+
+  extends: { connectionEntity },
+
+  schema: z.object({
+    /**
+     * The name of the database.
+     */
+    name: z.string(),
+  }),
+
+  meta: {
+    color: "#22adf6",
+  },
+})
+
+/**
+ * Creates a database in an InfluxDB 3 instance.
+ */
+export const database = defineUnit({
+  type: "influxdb3.database.v1",
+
+  args: {
+    /**
+     * The name of the database.
+     *
+     * If not provided, it will be set to the unit name.
+     */
+    databaseName: z.string().optional(),
+
+    /**
+     * The retention period for the database.
+     *
+     * The value is passed through to InfluxDB 3 as-is.
+     */
+    retention_period: z.string().optional(),
+  },
+
+  inputs: {
+    connection: connectionEntity,
+  },
+
+  outputs: {
+    database: databaseEntity,
+  },
+
+  meta: {
+    title: "InfluxDB 3 Database",
+    icon: "simple-icons:influxdb",
+    category: "Databases",
+  },
+
+  source: {
+    package: "@highstate/influxdb3",
+    path: "units/database",
+  },
+})
+
+export type Connection = EntityValue<typeof connectionEntity>
+export type ConnectionInput = EntityInput<typeof connectionEntity>
+export type Database = EntityValue<typeof databaseEntity>
+export type DatabaseInput = EntityInput<typeof databaseEntity>