@an5/adapters 0.2.11 → 0.2.14

package/java/src/main/java/an5/adapters/An5ViewClient.java

@@ -0,0 +1,107 @@
+package an5.adapters;
+
+import java.sql.SQLException;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A read-only client for a database view.
+ *
+ * <p>Reads go straight to the underlying table client, which already knows how to select
+ * from an arbitrary name. Every mutation is refused rather than attempted: a view has no
+ * rows to write, and the databases disagree about whether the statement is even legal, so
+ * the error is raised here where it can name the reason.
+ */
+public class An5ViewClient {
+
+  private final An5TableClient client;
+  private final String viewName;
+
+  public An5ViewClient(An5Adapter adapter, String viewName) {
+    this.client = adapter.table(viewName);
+    this.viewName = viewName;
+  }
+
+  public String viewName() {
+    return viewName;
+  }
+
+  public List<Map<String, Object>> findMany() throws SQLException {
+    return client.findMany();
+  }
+
+  public List<Map<String, Object>> findMany(An5Query query) throws SQLException {
+    return client.findMany(query);
+  }
+
+  public Map<String, Object> findFirst(An5Query query) throws SQLException {
+    return client.findFirst(query);
+  }
+
+  public Map<String, Object> findFirst(Map<String, Object> where) throws SQLException {
+    return client.findFirst(where);
+  }
+
+  public Map<String, Object> findUnique(An5Query query) throws SQLException {
+    return client.findUnique(query);
+  }
+
+  public Map<String, Object> findUnique(Map<String, Object> where) throws SQLException {
+    return client.findUnique(where);
+  }
+
+  public long count() throws SQLException {
+    return client.count();
+  }
+
+  public long count(Map<String, Object> where) throws SQLException {
+    return client.count(where);
+  }
+
+  public Map<String, Object> aggregate(An5Aggregate aggregate) throws SQLException {
+    return client.aggregate(aggregate);
+  }
+
+  public List<Map<String, Object>> groupBy(An5GroupBy group) throws SQLException {
+    return client.groupBy(group);
+  }
+
+  public List<Map<String, Object>> vectorSearch(
+      double[] vector, Integer take, Map<String, Object> where, String vectorField, String metric)
+      throws SQLException {
+    return client.vectorSearch(vector, take, where, vectorField, metric);
+  }
+
+  public Map<String, Object> create(Map<String, Object> data) throws SQLException {
+    throw readOnly("create");
+  }
+
+  public Map<String, Object> update(Map<String, Object> where, Map<String, Object> data)
+      throws SQLException {
+    throw readOnly("update");
+  }
+
+  public Map<String, Object> updateMany(Map<String, Object> where, Map<String, Object> data)
+      throws SQLException {
+    throw readOnly("updateMany");
+  }
+
+  public Map<String, Object> delete(Map<String, Object> where) throws SQLException {
+    throw readOnly("delete");
+  }
+
+  public Map<String, Object> deleteMany(Map<String, Object> where) throws SQLException {
+    throw readOnly("deleteMany");
+  }
+
+  public Map<String, Object> upsert(
+      Map<String, Object> where, Map<String, Object> createData, Map<String, Object> updateData)
+      throws SQLException {
+    throw readOnly("upsert");
+  }
+
+  private UnsupportedOperationException readOnly(String operation) {
+    return new UnsupportedOperationException(
+        "View '" + viewName + "' is read-only; " + operation + " is not allowed on it.");
+  }
+}

package/java/src/main/java/an5/adapters/base/Dialect.java

@@ -0,0 +1,103 @@
+package an5.adapters.base;
+
+import java.util.Locale;
+
+/**
+ * The database dialects AN5 speaks, together with everything that differs between them.
+ *
+ * <p>The differences are not cosmetic. Quoting, pagination and the {@code WITH (NOLOCK)}
+ * hint each have to be produced per dialect, and getting one wrong yields SQL the target
+ * engine cannot parse — so all of it is decided here rather than at each call site.
+ */
+public enum Dialect {
+  MSSQL("mssql"),
+  POSTGRES("postgres"),
+  SQLITE("sqlite");
+
+  private final String id;
+
+  Dialect(String id) {
+    this.id = id;
+  }
+
+  /** The lower-case identifier used in connection strings and generated metadata. */
+  public String id() {
+    return id;
+  }
+
+  /**
+   * The dialect a connection string points at.
+   *
+   * <p>Lower-cased first: a URI scheme is case-insensitive, so {@code MySQL://} and
+   * {@code mysql://} are the same connection.
+   */
+  public static Dialect detect(String connectionString) {
+    String cs = connectionString == null ? "" : connectionString.trim().toLowerCase(Locale.ROOT);
+    if (cs.startsWith("postgres://") || cs.startsWith("postgresql://")) {
+      return POSTGRES;
+    }
+    if (cs.startsWith("sqlite://")
+        || cs.startsWith("sqlite:")
+        || cs.startsWith("file:")
+        || cs.endsWith(".db")
+        || cs.endsWith(".sqlite")
+        || cs.endsWith(".sqlite3")
+        || cs.equals(":memory:")) {
+      return SQLITE;
+    }
+    return MSSQL;
+  }
+
+  /**
+   * The JDBC bind placeholder.
+   *
+   * <p>Always {@code ?}: every JDBC driver binds positionally. PostgreSQL's {@code %s} is
+   * a psycopg2-only spelling, so the other adapters' dialect split does not carry over.
+   */
+  public String placeholder() {
+    return "?";
+  }
+
+  /** Quotes a bare column or identifier name for this dialect. */
+  public String quoteIdentifier(String name) {
+    String raw = stripWrapping(name, "[", "]");
+    if (this == MSSQL) {
+      return "[" + raw.replace("]", "]]") + "]";
+    }
+    String unwrapped = stripWrapping(raw, "\"", "\"");
+    return "\"" + unwrapped.replace("\"", "\"\"") + "\"";
+  }
+
+  /** {@code WITH (NOLOCK)} is an MSSQL table hint; no other dialect has an equivalent. */
+  public boolean supportsNolock() {
+    return this == MSSQL;
+  }
+
+  /**
+   * The trailing limit clause.
+   *
+   * <p>SQLite has {@code LIMIT ... OFFSET} like PostgreSQL. Emitting the MSSQL
+   * {@code OFFSET ... FETCH NEXT} form against SQLite produces SQL it cannot parse, so
+   * the two are kept apart deliberately.
+   */
+  public String pagination(Integer take, int skip, String orderSql) {
+    if (take == null) {
+      return "";
+    }
+    if (this == MSSQL) {
+      String prefix = orderSql == null || orderSql.isEmpty() ? " ORDER BY (SELECT NULL)" : "";
+      return prefix + " OFFSET " + Math.max(0, skip) + " ROWS FETCH NEXT " + take + " ROWS ONLY";
+    }
+    return " LIMIT " + take + " OFFSET " + Math.max(0, skip);
+  }
+
+  private static String stripWrapping(String name, String left, String right) {
+    String value = name == null ? "" : String.valueOf(name);
+    if (value.length() >= left.length() + right.length()
+        && value.startsWith(left)
+        && value.endsWith(right)) {
+      return value.substring(left.length(), value.length() - right.length());
+    }
+    return value;
+  }
+}

package/java/src/main/java/an5/adapters/base/FieldMeta.java

@@ -0,0 +1,42 @@
+package an5.adapters.base;
+
+/** One column of a model, as emitted by the generator into the metadata module. */
+public final class FieldMeta {
+  public final String name;
+  public final String type;
+  public final String sqlType;
+  public final boolean optional;
+  public final boolean hasDefault;
+  public final boolean id;
+  public final String description;
+
+  public FieldMeta(
+      String name,
+      String type,
+      String sqlType,
+      boolean optional,
+      boolean hasDefault,
+      boolean id,
+      String description) {
+    this.name = name;
+    this.type = type;
+    this.sqlType = sqlType;
+    this.optional = optional;
+    this.hasDefault = hasDefault;
+    this.id = id;
+    this.description = description;
+  }
+
+  /** The primary key column of a model, or {@code null} when the schema marks none. */
+  public static FieldMeta idField(java.util.List<FieldMeta> fields) {
+    if (fields == null) {
+      return null;
+    }
+    for (FieldMeta field : fields) {
+      if (field.id) {
+        return field;
+      }
+    }
+    return null;
+  }
+}

package/java/src/main/java/an5/adapters/base/JdbcUrls.java

@@ -0,0 +1,201 @@
+package an5.adapters.base;
+
+import java.util.Locale;
+import java.util.Properties;
+
+/**
+ * Connection strings to JDBC URLs.
+ *
+ * <p>A JDBC URL is mandatory and positional, while the connection strings the rest of AN5
+ * takes are ADO-style or URI-style. Every environment spellings are accepted here so a
+ * project can keep one {@code DATABASE_URL} across all its clients.
+ */
+public final class JdbcUrls {
+
+  private JdbcUrls() {}
+
+  /** The JDBC URL for a connection string, for the dialect it points at. */
+  public static String url(String connectionString) {
+    Dialect dialect = Dialect.detect(connectionString);
+    String url = urlFor(dialect, connectionString);
+    if (url != null) {
+      return url;
+    }
+    throw new IllegalArgumentException(
+        "Unsupported connection string for " + dialect.id() + ": " + connectionString);
+  }
+
+  private static String urlFor(Dialect dialect, String connectionString) {
+    if (connectionString == null) {
+      return null;
+    }
+    String value = connectionString.trim();
+    if (dialect == Dialect.SQLITE) {
+      return sqliteUrl(value);
+    }
+    if (dialect == Dialect.POSTGRES) {
+      return postgresUrl(value);
+    }
+    return mssqlUrl(value);
+  }
+
+  /**
+   * SQLite needs no server, so the path is the whole URL.
+   *
+   * <p>The {@code sqlite:} and {@code sqlite://} wrappers are stripped one at a time and
+   * only then is {@code file:} looked for: {@code sqlite:file::memory:?cache=shared} is
+   * only a URI after {@code sqlite:} is gone, so one combined check would miss it.
+   */
+  private static String sqliteUrl(String value) {
+    String[] prefixes = {"sqlite:///", "sqlite://", "sqlite:"};
+    String lower = value.toLowerCase(Locale.ROOT);
+    for (String prefix : prefixes) {
+      if (lower.startsWith(prefix)) {
+        value = value.substring(prefix.length());
+        break;
+      }
+    }
+    // `sqlite:///C:/data/app.db` leaves a leading slash that belongs to the URL, not the
+    // path, on Windows.
+    if (value.length() > 2 && value.charAt(0) == '/' && value.charAt(2) == ':') {
+      value = value.substring(1);
+    }
+    if (value.isEmpty()) {
+      value = ":memory:";
+    }
+    return "jdbc:sqlite:" + value;
+  }
+
+  private static String postgresUrl(String value) {
+    String lower = value.toLowerCase(Locale.ROOT);
+    if (lower.startsWith("postgres://")) {
+      return "jdbc:postgresql://" + value.substring("postgres://".length());
+    }
+    if (lower.startsWith("postgresql://")) {
+      return "jdbc:postgresql://" + value.substring("postgresql://".length());
+    }
+    return null;
+  }
+
+  /**
+   * SQL Server is reached either through a {@code jdbc:sqlserver:} URL, which is passed
+   * through untouched, or through the ADO-style {@code Server=...;Database=...} string the
+   * other adapters take.
+   */
+  private static String mssqlUrl(String value) {
+    String lower = value.toLowerCase(Locale.ROOT);
+    if (lower.startsWith("jdbc:")) {
+      return value;
+    }
+    if (lower.startsWith("sqlserver://")) {
+      value = value.substring("sqlserver://".length());
+      lower = value.toLowerCase(Locale.ROOT);
+    }
+
+    String[] parts = value.split(";");
+    String host = "";
+    String port = "1433";
+    String database = "";
+    for (int i = 0; i < parts.length; i++) {
+      String part = parts[i].trim();
+      int at = part.indexOf('=');
+      if (at < 0) {
+        continue;
+      }
+      String key = part.substring(0, at).trim().toLowerCase(Locale.ROOT);
+      String entry = part.substring(at + 1).trim();
+      if (key.equals("server") || key.equals("data source") || key.equals("host") || key.equals("address")) {
+        // ADO spells the port as a comma (`Server=db,1433`); a JDBC URL as a colon. Both
+        // reach this function, so both separators have to be read.
+        int colon = entry.lastIndexOf(':');
+        int comma = entry.lastIndexOf(',');
+        int portSeparator = Math.max(colon, comma);
+        if (portSeparator > 0 && isNumeric(entry.substring(portSeparator + 1))) {
+          host = entry.substring(0, portSeparator);
+          port = entry.substring(portSeparator + 1);
+        } else {
+          host = entry;
+        }
+      } else if (key.equals("port")) {
+        port = entry;
+      } else if (key.equals("database") || key.equals("initial catalog")) {
+        database = entry;
+      }
+    }
+    if (host.isEmpty()) {
+      return null;
+    }
+    String url = "jdbc:sqlserver://" + host + ":" + port;
+    if (!database.isEmpty()) {
+      url += ";databaseName=" + database;
+    }
+    return url + ";encrypt=true;trustServerCertificate=true";
+  }
+
+  /**
+   * The username and password from a connection string, or {@code null} for either when
+   * the string carries none — Windows integrated authentication has both absent.
+   */
+  public static String[] credentials(String connectionString) {
+    if (connectionString == null) {
+      return new String[] {null, null};
+    }
+    String user = null;
+    String password = null;
+    for (String part : connectionString.split(";")) {
+      int separator = part.indexOf('=');
+      if (separator < 0) {
+        continue;
+      }
+      String key = part.substring(0, separator).trim().toLowerCase(Locale.ROOT);
+      String value = part.substring(separator + 1).trim();
+      if (key.equals("user") || key.equals("uid") || key.equals("user id")) {
+        user = value;
+      } else if (key.equals("password") || key.equals("pwd")) {
+        password = value;
+      }
+    }
+    return new String[] {user, password};
+  }
+
+  /**
+   * The SQLite file path, or {@code null} for an in-memory database.
+   *
+   * <p>An in-memory database does not survive every connection being closed, so
+   * {@code An5Adapter} keeps one connection open for exactly this case.
+   */
+  public static boolean isMemory(String connectionString) {
+    if (connectionString == null) {
+      return true;
+    }
+    String value = connectionString.trim().toLowerCase(Locale.ROOT);
+    if (value.equals(":memory:")) {
+      return true;
+    }
+    return value.contains("mode=memory") || value.startsWith("sqlite::memory:");
+  }
+
+  /** The connection properties for a username and password, either of which may be {@code null}. */
+  public static Properties properties(String username, String password) {
+    Properties properties = new Properties();
+    if (username != null) {
+      properties.setProperty("user", username);
+    }
+    if (password != null) {
+      properties.setProperty("password", password);
+    }
+    return properties;
+  }
+
+  private static boolean isNumeric(String value) {
+    if (value.isEmpty()) {
+      return false;
+    }
+    for (int i = 0; i < value.length(); i++) {
+      if (!Character.isDigit(value.charAt(i))) {
+        return false;
+      }
+    }
+    return true;
+  }
+}

package/java/src/main/java/an5/adapters/base/Metadata.java

@@ -0,0 +1,195 @@
+package an5.adapters.base;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * The generated model's table names, columns and relations, registered at start-up.
+ *
+ * <p>The generated client calls {@link #setAdapterMetadata(Map)} once before it hands out a
+ * table client. Nothing here reads the schema, so the adapter stays independent of the
+ * generator.
+ */
+public final class Metadata {
+
+  private static final Map<String, String> MODEL_TO_TABLE = new LinkedHashMap<String, String>();
+  private static final Map<String, List<FieldMeta>> MODEL_FIELDS =
+      new LinkedHashMap<String, List<FieldMeta>>();
+  private static final Map<String, Map<String, RelationDef>> RELATION_MAP =
+      new LinkedHashMap<String, Map<String, RelationDef>>();
+
+  private Metadata() {}
+
+  /**
+   * Replaces the registry with the metadata the generated client passed in.
+   *
+   * <p>Called once per client, so it clears first: a second client for another schema in
+   * the same JVM must not see the first one's tables.
+   */
+  public static synchronized void setAdapterMetadata(Map<String, ?> metadata) {
+    MODEL_TO_TABLE.clear();
+    MODEL_FIELDS.clear();
+    RELATION_MAP.clear();
+    if (metadata == null) {
+      return;
+    }
+
+    putStringMap(MODEL_TO_TABLE, first(metadata, "model_to_table", "modelToTable"));
+
+    Map<String, ?> rawFields = first(metadata, "model_fields", "modelFields");
+    if (rawFields != null) {
+      for (Map.Entry<String, ?> entry : rawFields.entrySet()) {
+        MODEL_FIELDS.put(entry.getKey(), readFields(entry.getValue()));
+      }
+    }
+
+    Map<String, ?> rawRelations = first(metadata, "relation_map", "relationMap", "RELATION_MAP");
+    if (rawRelations != null) {
+      for (Map.Entry<String, ?> entry : rawRelations.entrySet()) {
+        Object value = entry.getValue();
+        if (!(value instanceof Map)) {
+          continue;
+        }
+        Map<String, RelationDef> forModel = new LinkedHashMap<String, RelationDef>();
+        for (Map.Entry<?, ?> rel : ((Map<?, ?>) value).entrySet()) {
+          if (!(rel.getValue() instanceof Map)) {
+            continue;
+          }
+          Map<?, ?> defn = (Map<?, ?>) rel.getValue();
+          forModel.put(
+              String.valueOf(rel.getKey()),
+              new RelationDef(
+                  string(defn, "modelName", "model_name", "model"),
+                  string(defn, "relationType", "relation_type", "type"),
+                  string(defn, "foreignKey", "foreign_key"),
+                  string(defn, "localKey", "local_key")));
+        }
+        RELATION_MAP.put(entry.getKey(), forModel);
+      }
+    }
+  }
+
+  /**
+   * The model's name as the metadata keys it, accepting a different capitalisation.
+   *
+   * <p>The generated client registers tables under their PascalCase name while the metadata
+   * keys them in camelCase. A plain lookup would find no columns at all and silently skip
+   * {@code isId} — never generating the primary key.
+   */
+  public static String resolveModelKey(String modelName) {
+    if (modelName == null || modelName.isEmpty()) {
+      return modelName;
+    }
+    if (MODEL_TO_TABLE.containsKey(modelName) || MODEL_FIELDS.containsKey(modelName)) {
+      return modelName;
+    }
+    String camel = Character.toLowerCase(modelName.charAt(0)) + modelName.substring(1);
+    if (MODEL_TO_TABLE.containsKey(camel) || MODEL_FIELDS.containsKey(camel)) {
+      return camel;
+    }
+    String lower = modelName.toLowerCase();
+    if (MODEL_TO_TABLE.containsKey(lower) || MODEL_FIELDS.containsKey(lower)) {
+      return lower;
+    }
+    return modelName;
+  }
+
+  /** The table name a model maps to, or the model name when the schema used none. */
+  public static String resolveTable(String modelName) {
+    String key = resolveModelKey(modelName);
+    String table = MODEL_TO_TABLE.get(key);
+    return table == null ? modelName : table;
+  }
+
+  public static List<FieldMeta> fieldsFor(String modelName) {
+    List<FieldMeta> fields = MODEL_FIELDS.get(resolveModelKey(modelName));
+    if (fields == null) {
+      fields = MODEL_FIELDS.get(modelName);
+    }
+    return fields == null ? Collections.<FieldMeta>emptyList() : fields;
+  }
+
+  public static Map<String, RelationDef> relationsFor(String modelName) {
+    Map<String, RelationDef> relations = RELATION_MAP.get(modelName);
+    if (relations == null) {
+      relations = RELATION_MAP.get(resolveModelKey(modelName));
+    }
+    return relations == null ? Collections.<String, RelationDef>emptyMap() : relations;
+  }
+
+  /** A snapshot of the registered table map, for callers that want to inspect it. */
+  public static Map<String, String> modelToTable() {
+    synchronized (Metadata.class) {
+      return Collections.unmodifiableMap(new LinkedHashMap<String, String>(MODEL_TO_TABLE));
+    }
+  }
+
+  private static List<FieldMeta> readFields(Object value) {
+    List<FieldMeta> fields = new ArrayList<FieldMeta>();
+    if (!(value instanceof List)) {
+      return fields;
+    }
+    for (Object entry : (List<?>) value) {
+      if (!(entry instanceof Map)) {
+        continue;
+      }
+      Map<?, ?> field = (Map<?, ?>) entry;
+      fields.add(
+          new FieldMeta(
+              string(field, "name"),
+              string(field, "type"),
+              string(field, "sql", "sqlType"),
+              bool(field, "isOptional", "optional"),
+              bool(field, "hasDefault", "default"),
+              bool(field, "isId", "id"),
+              string(field, "description")));
+    }
+    return fields;
+  }
+
+  private static void putStringMap(Map<String, String> target, Object value) {
+    if (!(value instanceof Map)) {
+      return;
+    }
+    for (Map.Entry<?, ?> entry : ((Map<?, ?>) value).entrySet()) {
+      target.put(String.valueOf(entry.getKey()), entry.getValue() == null ? null : String.valueOf(entry.getValue()));
+    }
+  }
+
+  @SuppressWarnings("unchecked")
+  private static Map<String, ?> first(Map<String, ?> source, String... keys) {
+    for (String key : keys) {
+      Object value = source.get(key);
+      if (value instanceof Map) {
+        return (Map<String, ?>) value;
+      }
+    }
+    return null;
+  }
+
+  private static String string(Map<?, ?> source, String... keys) {
+    for (String key : keys) {
+      Object value = source.get(key);
+      if (value != null) {
+        return String.valueOf(value);
+      }
+    }
+    return null;
+  }
+
+  private static boolean bool(Map<?, ?> source, String... keys) {
+    for (String key : keys) {
+      Object value = source.get(key);
+      if (value instanceof Boolean) {
+        return (Boolean) value;
+      }
+      if (value instanceof String) {
+        return Boolean.parseBoolean((String) value);
+      }
+    }
+    return false;
+  }
+}

package/java/src/main/java/an5/adapters/base/RelationDef.java

@@ -0,0 +1,26 @@
+package an5.adapters.base;
+
+/**
+ * One relation of a model, as emitted by the generator into the metadata module.
+ *
+ * <p>{@code relationType} is {@code "one"} or {@code "many"}. The two sides of the join
+ * are named the way the foreign key is stored: {@code foreignKey} is the column on the
+ * related model that points back, {@code localKey} the column on this model it points to.
+ */
+public final class RelationDef {
+  public final String modelName;
+  public final String relationType;
+  public final String foreignKey;
+  public final String localKey;
+
+  public RelationDef(String modelName, String relationType, String foreignKey, String localKey) {
+    this.modelName = modelName;
+    this.relationType = relationType == null || relationType.isEmpty() ? "many" : relationType;
+    this.foreignKey = foreignKey;
+    this.localKey = localKey;
+  }
+
+  public boolean isMany() {
+    return "many".equals(relationType);
+  }
+}